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。