AI 协作项目管理（技能入口）
定位：通用型项目管理技能，不为特定项目服务。
核心命题：项目可以复杂沉重，AI 接手只读所需——上手成本（onboarding cost）不随项目规模增长。
本文件的职责只有一个：路由。 它回答"该读哪个文件"，不承载协议细则。
数值口径：正文一律用占位符 {{config:<键>}}；查值顺序见 MANIFEST.md 的「数值口径」节。
版本：唯一落点在 MANIFEST.md。
展示与反馈：网页版蓝图 <https://zyzep6f7.qwenwork.host/>（给人看的展示面，不一致时以包内为准）｜
使用问题与改进建议：2576124003@qq.com（分流规则见文末「反馈」节）。
Agent setup：若你的 Agent 不会自动加载技能文件（如 Claude Code），
每个会话开始时读一次 references/agent-compatibility.md。
---
启动先看四件事
准入门槛（只此一条）：不先知道就会返工、或会破坏契约。 不满足这条的，一律按需拉取——把它们列进来只会让这一屏变成没人读的第二份目录。
① **什么形态** —— 卡片 / 轻量工作区 / 完整工作区？
判据见 `references/onboarding.md` §1（命中即停，从严到宽）。**形态定错是唯一需要重建的决定。**
② **项目地图在哪** —— `MAP.md`：环境 / 规则 / 协议速记 / 路径注册表。
**可单独使用**：只存在一个 MAP 也能回答「项目在哪、代码在哪、按什么规则运转」。
③ **写代码的规矩** —— 一屏速查卡 `references/cheatsheet.md`；细则两本：**判据**（有阈值、可机检）`references/code-quality.md`，**风格与工作方式**（靠人读）`references/code-style.md`。
**不先知道，写出来的代码会被门禁拦下——那是返工，不是审查。**
④ **门禁怎么跑** —— 固定命令见 `references/cheatsheet.md` 末尾。
门禁由「跑脚本看退出码」给出，不由「读文档判断」给出。首次对话若判定为卡片模式：只需 templates/CARD.md 一个文件，本技能的其余部分不必读。
根目录入口优先级（两个视角，不要读串）：
- 使用者视角——用本技能管项目：README.md（这是什么 / 怎么开始）→ 本文件（路由）。
- 维护者视角——改本技能本身：MANIFEST.md（清单与版本）→references/change-control.md（改造门禁，六条缺一不得动手）。
两个视角的交集只有一处：协议正文都在 references/，入口文件从不承载细则。
---
可独立使用的四个子能力
这张表回答"我只要其中一件，行不行"。 答案：行——每个都能单独用；最小集见 MANIFEST.md 的「子能力与最小集」。
| 子能力 | 一句话 | 单独使用时的入口 | |---|---|---| | 项目地图 MAP | 项目在哪 / 代码在哪 / 按什么规则运转 | 一个 MAP.md（templates/MAP.template.md） | | 任务卡 | 一件事一张卡，换人或换窗口时只读卡就能接上 | 单文件卡 templates/CARD.md；要索引与门禁时用 templates/tasks/TASK_CARD.template.md | | 设计卡 | 先定方案：一屏蓝图给人看方向，详述留理由；未批准不生成执行卡 | references/design.md（详述 + 蓝图两件套） | | 代码书写规范 | 判据（可机检）+ 风格（靠人读），两本 | references/code-quality.md · references/code-style.md · scripts/code_metrics.py |
不够再升：从单件起步、按需扩集成完整工作区，历史不回写。
合起来用不用翻译：四者共享同一套术语、字段名与取值口径——这是有意的耦合，拆开就破坏功能。
---
Skill directory
按需加载，不要一次全读。
| 位置 | 用途 | |---|---| | references/cheatsheet.md | 一屏速查卡——接手三步 / 作业四条 / 提交四件 / 绝不做五条 / 固定命令 | | references/onboarding.md | 首次接入——形态判定（卡片 / 轻量 / 完整）/ 初始化清单 / 脚本就位 | | references/workflow.md | 功能域·生命周期——认领 / 作业 / 提交 / 归档 / 人眼查看 | | references/artifacts.md | 功能域·产物——卡 / 记录 / 索引 / 快照 / 地图的 schema；冻结区在此 | | references/concurrency.md | 功能域·并发——单写者 / 原子写 / CAS / 冲突文件 / 编号分配 | | references/audit.md | 功能域·审计——四类锚点 / 各检查项 / 自检清单 | | references/recovery.md | 功能域·恢复——缺失补全 / 断链 / 快照 / 卡重建 / 版本过时 | | references/code-quality.md | 功能域·代码质量（可机检的判据）——三档阈值 / 豁免机制 / 覆盖率 / 依赖方向 / 异常自愈 | | references/code-style.md | 功能域·代码风格（靠人读的约定）——命名 / 版面 / 抽象复用 / 重构三回合 / 范例库 / 提交信息 | | references/design.md | 功能域·设计——两件套（详述 + 蓝图）/ 成本纪律 / 生命周期与批准门禁 / 设计区与归档 | | references/collaboration.md | 功能域·协作——模式 / 角色 / 稳定 ID / 任务简报（设计规则已移至上行） | | references/change-control.md | 功能域·治理——改本技能本身前必读（含耦合警示与改动前六问） | | references/glossary.md | 术语表：标准术语 ↔ 历史叫法 对照（新写文档一律用标准术语） | | references/agent-compatibility.md | 无自动加载能力的 Agent（如 Claude Code）的登记办法 | | scripts/ | 可执行脚本（见下）——先跑脚本，再让人看；scripts/local/ 是项目自定义脚本（升级不覆盖） | | templates/ | 初始化骨架；含 templates/CARD.md 单文件工作卡（可脱离工作区使用） | | config/defaults.yml | 出厂默认值（实例真值在实例 MAP 规则段） | | ci/ | CI 接线样板（GitHub Actions 等）——不属技能正文 | | examples/ | 范例库骨架（索引表 / 入库流程 / project 与 external 两分区）——本体由项目自行积累 | | adapters/ | 按语言落地附录（python / java / javascript），不属技能正文 | | LEGACY_ONBOARDING.md | 存量项目接入（轻量登记 + 渐进整理，不深挖历史） | | README.md | 使用指南：这是什么 + 怎么开始 | | MANIFEST.md | 版本与文件清单声明（单一权威源） | | BLUEPRINT.md + blueprint/ | 设计蓝图（分页，8 页）——第 1 页总览；第 7 页「强耦合与不变量」是改本技能前的必读页（只记设计要点，不承载协议） | | tools/ | 可选工具区：可视化 / 定时 / 报告规范（只放规范不放实现，按需拉动） | | archives/ | 归档说明 |
---
接手只做三件事
① 读任务卡 tasks\<卡>.md —— 定位工作，不漫读全项目
② 沿指针读记录 卡上「上次交接」→ reports\<一篇>
③ 需要全局判断时 STATE.md（当前快照） / MAP.md（环境与结构）除此之外的一切文件都是按需拉取，不进接手路径。读完这三步仍不够，再查上面的目录表。
口径修正：「一份卡 + 一篇记录」说的是"读哪些"，不是"读多少"。
成本要用字符量，不能用文件数量——实测某真实项目：卡中位 5,445 字符、记录中位 3,505 字符，
即"两份文件"≈ 8,900 字符，而单张卡最大 22,002 字符。文件数恒定 ≠ 成本恒定。
量尺由scripts/overview.py给（「接手包」一行）：卡 + 指针记录字符数 vs{{config:capacity.onboarding_max_chars}}，
单卡上限 {{config:capacity.card_max_chars}}。读进来的东西会留在上下文里——
成本不是"读了几份"，是"带了多少字符走完整场对话"。
---
核心不变量（invariants — 改任何东西都不得破坏）
完整清单与理由见 references/change-control.md 的「不变量」节。
此处只列接手者必须知道的五条。
- 记录指针链：任务卡「上次交接」→ 记录「下一步」→ 索引 [接力] 行——上手成本恒定的承重墙。
- 分层索引：索引热区只保留最近若干行，冷区（归档文件）保有全量；行移入不删除。
- 每篇记录最多被读一次：读过即把增量写回任务卡（write-back）。
- 档案只进不出：
reports\与archives\下文件禁删禁移（唯一例外＝归档流程，且移后必须同步索引行指向）。 - 数据诚实边界：恢复不出的内容标「数据待补」，禁止伪造。
---
脚本（随包分发，不必手写）
跑哪些由形态决定：卡片模式一个都不跑；light 提交时两个（机械步骤 + 门禁）；standard 再加核查三件套。
矩阵见 references/onboarding.md §4.0——先看形态，再看下表。
| 脚本 | 用途 | 何时跑 | |---|---|---| | scripts/overview.py | 一屏全貌（地图 / 快照 / 索引热区 / 活跃卡 / 决策点）——视图，不是门禁，恒返回 0 | 接手前 10 秒 / 定期扫视 | | scripts/validate_workspace.py | 工作区结构与配置校验（含人检标记格式与到期） | 初始化后 / 改结构后 | | scripts/check_closeout.py | 提交流程门禁（6+1 块 / 移卡存在 / 索引已登记 / 快照已更新） | 每次提交前 | | scripts/closeout.py | 机械步骤总入口（建卡 new-card / 记录骨架 / 索引双写 / 滚动归档 / 卡归档 / 留痕滚动 reviews-archive）——不要手改共享文件 | 每次提交时 / 用户说「新建任务」时 | | scripts/audit_all.py | 全盘核查（编排全部门禁 + 机器戳留痕 + 超期自查）——开了却没跑会自己变红 | 定期 / 接手前 | | scripts/setup.py | 首次启动配置向导（本地 git 备份 / 核查周期） | 首次建工作区 | | scripts/check_index.py | 索引完整性（编号递增 / 类型合法 / 指针不悬空 / 冷热一致） | 改索引后 / 定期 | | scripts/reconcile.py | 三方一致性（快照 ↔ 记录 ↔ 索引）+ 时间锚 + 容量口径 | 定期 / 怀疑账实不符 | | scripts/code_metrics.py | 代码度量门禁（三档阈值 + 豁免理由真伪） | 每次改代码后 | | scripts/gen_views.py | 派生视图生成 + 版本一致性 + 配置占位符校验 | 改协议后 | | scripts/stamp.py | 机器戳与 AI 标识生成 / 校验 | 认领任务卡 / 写人检标记时 | | scripts/new_local.py | 项目专属脚本脚手架 | 通用门禁覆盖不到时 | | scripts/selftest_gates.py | 门禁变异自检（注入故障，断言门禁必须变红） | 改门禁后 / CI 第一步 |
用法：python scripts/<脚本名>.py <工作区根> —— 三态输出 [通过] / [问题] / [待核]（另有 [建议]，只提示不计数），退出码 0/1/2/3（1 = 有[问题]，2 = 仅[待核]，3 = 脚本自身错误）。
---
反馈
用这个技能遇到问题、或有改进建议，请发邮件到 2576124003@qq.com。
- 项目内部的问题先记进工作区
REVIEWS.md（元数据通道，追加式）；提级给包作者时一并附上。 - 属于包本身的缺陷（条款矛盾、脚本误报、门禁失效）请直接发信，并尽量附上：跑的是哪个脚本、退出码、以及能复现的最小工作区形态。
- 改造这个包之前先读
references/change-control.md；若拟议改动与功能契约冲突，按该文件的「冲突即提醒」处理。
---
使用前提与边界
使用前提：只有两条——本地文件系统与命令/文件执行能力（能落盘目录、读写任务卡与记录）。
平台无关：不依赖任何平台私有接口、技能系统或 API。技能系统有则装，无则按文档读取。 不适用：无本地文件能力的场景（网页对话 / 移动端 / 纯对话 / API 裸调）。
边界声明（分界线不是"实现 / 不实现"，而是"调用即执行 / 常驻自动触发"）：
- 随包提供、默认启用·调用即执行：协议正文、模板、可执行脚本（结构校验 / 提交门禁 / 索引双写 / 归档 / 一致性对账 / 代码度量 / 机器戳）。
- 不实现、也不默认启用·常驻自动触发：运行时守护进程、权限系统、定时或事件驱动地自动跑、把 AI 行为实时管住的持续监督。
"运行时守护进程"指什么：一个常驻后台、在 AI 每次读写时实时介入的进程（拦截写入、强制加锁、自动回滚）。
不做它的两条理由：① 它需要运行时权限与平台能力，一旦打包就绑死平台；
② 它承诺的是"防呆"——而防呆一旦失效，使用者会以为"有它在就不会错"，比没有更危险。
本包换的是事后可审计：不拦你，但你做了什么一定会留痕。
归档器为什么可以做：它调用即执行、结果确定、失败可回滚，不是常驻触发——只是把手工动作写成了脚本。
默认开的判据不止一条：
① 烧不烧 token——脚本核查不消耗模型上下文 → 开；把检查写成「读文档判断」才烧。
② 会不会造成假账——开了就必须留痕（见 references/audit.md §6）：开关不是许可，是承诺，承诺由痕迹核实。
设计前提：文档协议不做、也做不到实时监督 AI——监督是脚本层的职责。
文档层的任务是事后可审计：每条声明至少有两个以上独立记录互证。
协议不为"AI 一定守规矩"而设计，为"不守规矩必留痕"而设计。