project-ai-docs
通用项目 AI 文档协议 skill：每项目一份 docs/.ai/ 认知库，agent 会话先读索引再动手、改动必回写，防上下文涣散、保项目认知精细。
英文版见 README.en.md。
通用法则
1. 地图先行 — index.md 唯一入口，全文档优先级路由表 2. 分层预算 — core/modules/config/best-practices 四层，显式优先级管 token 开销 3. 红线前置 — 硬约束（禁止项）放 index 最顶，先于一切技术信息 4. 点读代替全读 — 模块化文档，按任务只读相关切片 5. 写回闭环 — 任务结束 = 文档更新，知识沉淀在文档不靠会话记忆 6. 增量感知 — changelog 台账，新会话读尾部即知项目现状 7. 人机分离 — README 给用户，docs/.ai 给 agent 8. 事实可验 — 只写实测路径/版本/命令，不写猜测
内容
project-ai-docs/
├── skills/project-ai-docs/ # 运行时技能单元（DSH 插件式安装的发现根）
│ ├── SKILL.md # 协议本体（中文）
│ ├── SKILL.en.md # 协议英文版（替换式：改名覆盖 SKILL.md 即用）
│ ├── template/ # Init 骨架·中文（复制即用）
│ └── template.en/ # Init 骨架·英文
├── extensions/dsh/index.js # DSH bundle 适配器（provider 指向 skills/）
├── cordis.patch.yml # bundle 注册
├── package.json # npm 包清单（dsh.bundle.patch）
├── AGENTS.md # 项目级 agent 规则（英文，agent 通用）
├── .gitignore # git 忽略（node_modules / *.tgz / *.log）
├── .gitattributes # linguist 语言分析 + 行尾规范化
├── .github/workflows/publish.yml # npm 发布管道（手动触发）
├── README.md # 本文件（中文）
├── README.en.md # 英文说明
├── LICENSE # MIT
└── docs/.ai/ # 本包自身的认知库（协议自述）安装（DSH）
A：复制到技能发现根（零依赖，免构建）
| 层级 | 路径 |
|---|---|
| 用户级（推荐） | %USERPROFILE%\.dsh\skills\ |
| 全局 agents-home | %USERPROFILE%\.agents\skills\ |
| 项目级 | <项目根>\.dsh\skills\ 或 <项目根>\.agents\skills\ |
# 复制运行时技能单元（skills/project-ai-docs/ → ~/.dsh/skills/project-ai-docs/）
Copy-Item -Recurse D:\Desktop\project-ai-docs\skills\project-ai-docs "$env:USERPROFILE\.dsh\skills\project-ai-docs"
# 一般无需重启（watch 自动发现）；新会话未出现则重启 DSH 一次
# 卸载：删除目录即移除
Remove-Item -Recurse "$env:USERPROFILE\.dsh\skills\project-ai-docs"B：dsh plugin 安装（随 profile 管理）
# 标准：从 npm registry 安装（已发布 project-ai-docs@0.1.0）
dsh plugin --profile web add project-ai-docs
# 本地预发验证（未发布改动测试用）
dsh plugin --profile web add file:D:\Desktop\project-ai-docs
# 更新 / 卸载
dsh plugin --profile web up project-ai-docs
dsh plugin --profile web rm project-ai-docs> B 路利用包内 dsh.bundle.patch → cordis.patch.yml → extensions/dsh/index.js，把 skills/ 树注册为 DSH 技能源（同 Aegis 做法）。装完重启 DSH 生效。
其他宿主（Claude Code / Codex 等）：复制 skills/project-ai-docs/ 到各自 skills 路径即可。
使用
| 触发 | 行为 |
|---|---|
| 新会话开始 | 读 index + changelog，点读相关分层文档 |
| 「初始化项目文档」/「/init」 | Init 协议：扫描项目 → 建骨架 → 实测填充 |
| 任务完成后 | 清冗余 → 回写对应文档 → changelog 记账 |
给新项目的 Init 速查
# 1. 建骨架（agent 执行，或手动复制）
# 2. agent 扫描项目信号，按 SKILL.md §Init 填充
# 3. 校验所有路径/版本/命令有出处发布（手动）
仓库已带 GitHub Action（.github/workflows/publish.yml），手动触发，发布 package.json 当前版本：
1. 生成 npm Granular Access Token（GAT）（CI 用，免 OTP；npm 正限制 bypass-2FA token 直发，GAT 是官方推荐）： - 网页：npmjs.com → Access Tokens → Generate New Token → Granular Access Token - 选 Publish packages 权限 + 过期时长；生成时 2FA 验证一次，之后发布免 OTP 2. 仓库 Settings → Secrets and variables → Actions → 新建 NPM_TOKEN，值粘贴该 token 3. 本地改好版本并提交：npm version 0.1.1（或手改 package.json）→ git commit/push 4. Actions 页 → publish → Run workflow（无输入，发布 package.json 当前版本） 5. 流程：读版本 → 查重（已发布则中止）→ npm pack --dry-run 校验包内容 → npm publish → 打 vX.Y.Z tag 推回
无需本地 npm login / publish。