dsh-project-brief ｜ 项目简报

给一个工程路径，一步产出可被机器判卷的项目分析文档：事实台账编号引用、章节写作规范、18 项确定性断言。

它把 skills/project-brief 的方法论（证据纪律 + 六阶段工作流 + 五种文档模式 + 反虚构纪律）做成 Harness 插件：开启后，你只要说"分析这个工程并写一份架构说明"，agent 就会 采事实 → 选文档类型 → 拿章节计划 → 写文档 → 跑断言 → 修到 PASS。

安装与启用

# 在任意工作区写一个包，然后用 plugin_manager 安装（不要手改 profile 的 package.json）
# 目标目录：plugins/dsh-project-brief

plugin_manager action=install_bundle target=/Users/xu/Documents/GitHub/ai/plugins/dsh-project-brief

安装后本插件在 profile 里是一行插件（id project-brief），在「设置 → 插件」里可开关； 关掉即卸载工具、命令、提示词段、输入框上方的面板与两个 Host 路由。

四种用法

用法	长什么样	说明
面板（傻瓜式）	输入框左下角「＋」圆圈 → 指令列表里选 project-brief → 输入框正上方弹出磨砂面板	选保存目录（默认当前工程根）、勾文档类型（可多选/不选）、写补充要求，点「生成文档」
对话	「分析 /path/to/repo，写一份架构说明」	agent 自动调 project_brief(action=prepare) → 写作 → action=verify
命令	/project-brief；/project-brief --direct /path/repo --doc=onboarding	默认开面板；--direct 跳过面板直接准备 kit 并排写作任务
直接调工具	project_brief(action="prepare", target="/path")	适合脚本化或子 agent

面板怎么用

1. 点输入框左下角的「＋」圆圈（宿主自带的指令菜单）→ 列表里选 project-brief。 选中后草稿变成 /project-brief，输入框正上方立刻弹出面板（不用回车）； 回车只会留一条「项目简报」命令行，点那条行也能重开面板。 面板与背景用磨砂玻璃分层：半透明底 + 背景模糊 + 细边框 + 纸纹噪点，深浅色主题都跟随 --dsw-alias-* 令牌。
2. 保存位置：默认是当前工程根目录；点「选择文件夹」可换目录。文档、事实台账、kit 都写到这里。
3. 生成类型：architecture / onboarding / spec / audit / handover，可多选，也可一个都不选（＝默认架构说明）。 多选时每类各出一份：project-brief-<类型>.md。
4. 补充要求：自由文本，例如「只看支付与风控；重点写失败重试；两篇都控制在 150 行内」。
5. 点「生成文档」→ 面板显示将生成的文件与要求存档路径，agent 立刻按计划写文档并逐篇 verify。

规则是并集 + 优先级：面板选项给默认集合，补充要求是增补；两者冲突时以补充要求为准 （范围、重点、篇幅、章节取舍都听输入框）。但检查器硬规则不让步——front matter、证据引用、 坑位 ≥5、不变量含检测、ADR 含放弃方案、单篇 120–1600 行，违反就会 FAIL。

要求本身会落盘为 <输出目录>/project-brief.requirement.md，交付时可回溯"当时到底要了什么"。

prepare 返回的东西就是"一步"的全部输入：

• 事实台账：F1–F15（文件数、语言分布、最大文件、依赖、入口、测试比、CI、git 热点、技术债、已有文档、目录分布），文档里用 [@F3] 引用；
• 章节计划：每节的必答问题、证据要求、反模式、行数预算、写作顺序（速览最后写）；
• 硬规则：与 18 项断言一一对应的写作约束；
• 路径：主文档、台账、kit、验收报告的位置。

写完调 project_brief(action="verify", target=...)，返回逐条 PASS/FAIL 与修复指引； PASS 18 / FAIL 0 才算交付。

文档类型

id	名称	模式	章节
architecture	架构说明（默认）	architecture	速览·全景·术语·流程·不变量·ADR·代码地图·待证
onboarding	上手文档	onboarding	速览·全景·术语·流程·坑·代码地图·运维·阅读路径
spec	反推需求规格	spec	速览·术语·流程·不变量·ADR·待证
audit	技术债审计	audit	速览·不变量·坑·ADR·待证
handover	交接文档	handover	速览·全景·坑·ADR·运维·待证·阅读路径

深度：quick ≤200 行 / standard 300–600 / deep 600–1200（检查器硬区间 120–1600）。

工程类型识别

内置 14 种打分识别器：Node/前端应用、Node 库、Python 服务/库、Go、Rust、JVM、移动端、 monorepo、基础设施仓库、数据/ML、纯文档仓库、Harness 插件、通用兜底。 识别结果不改章节集合，只改先读什么、哪些流程/不变量/坑值得写 —— 这就是"复杂工程也能给出针对性计划"的落点。

配置

cordis.patch.yml 里同名 id 覆盖即可，全部字段见 lib/config.js：

- id: project-brief
  name: dsh-project-brief
  config:
    outputDir: docs                 # 相对被分析工程根
    defaultDocType: architecture
    defaultDepth: standard
    defaultAudience: 新加入的工程师
    git: true                       # 关掉则不跑 git，私有/无 .git 目录也能用
    pythonPath: python3             # 找不到自动回落内置 JS 引擎，判定语义一致
    writeKit: true                  # 写 project-brief.kit.json（可追溯）
    seedDocument: false             # true 时预生成带占位符骨架（故意不过检）
    promptSection: true             # 是否向系统提示注入使用指引
    command: true                   # 是否注册 /project-brief
    composerPanel: true             # 是否启用输入框上方面板
    extensionDirs: []               # 扩展目录，见下
    extraRules: []                  # 追加到写作硬规则的团队约定

扩展（给后续开发者与 AI）

三类扩展，都是"放文件进目录 + 写进 extensionDirs"，不用改插件本体：

<extensionDir>/
├─ doc-types/*.js        新文档类型（精简/详尽/局部/流程图/纯文字……）
├─ project-types/*.js    新工程类型（游戏引擎、嵌入式、LaTeX、K8s Operator……）
└─ stages/*.js           新流水线阶段（prepare 加工上下文 / verify 追加断言）

• 现成脚手架：project_brief(action="scaffold", kind="doc-type", id="concise", target="<目录>")
• 跑得起来的示例：extensions/examples/（flow 流程图版、notebook-lab 识别器、verify 阶段）
• 设计约束与未来路线：docs/EXTENDING.md
• 内部结构与不变量：docs/ARCHITECTURE.md
• 给 AI 的最小上下文包：docs/AI-CONTRIBUTOR.md

文件结构

dsh-project-brief/
├─ client.js               Web 半边：输入框左侧「＋」+ 上方表单（选目录/选类型/写要求）
├─ lib/index.js            Host 入口：工具 / 命令 / 提示词（只做协议层）
├─ lib/ui-bridge.js        面板后端：catalog / run 两个路由 +「并集+优先级」写作任务
├─ lib/registry.js         内置 + 扩展的加载与校验
├─ lib/engine/             detect / scan / checkBuiltin / verify / plan / output / pipeline / rules
├─ lib/builtins/           章节规范、五种文档类型、工程类型识别器、阶段
├─ assets/                 scan_repo.py、check_brief.py、brief-template.md（与 skill 同源）
├─ extensions/             脚手架母版 + 三个示例扩展
├─ docs/                   ARCHITECTURE / EXTENDING / AI-CONTRIBUTOR
└─ test/run.mjs            15 条用例，含双引擎一致性

验收

node test/run.mjs          # 15 passed

真实工程上的闭环：

python3 assets/scan_repo.py <root> --json /tmp/facts.json
# 写文档 …
python3 assets/check_brief.py <doc> --facts /tmp/facts.json --root <root>
# PASS 18 / FAIL 0

本机已跑通的证据（dsh 0.2.1-rc.5 / Node 24 / Python 3.13）：

面板的渲染未做截图验证（当前会话没有浏览器控制）；已验证的是：client half 加载成功、 两个槽位注册 active、Host 路由单测通过。改完 client.js 后需要刷新页面一次才看到新 UI。

项	结果
安装	profile 依赖与 bundles 均含 dsh-project-brief，插件行 include:project-brief active（v0.3.0）
工具	project_brief 已注册（Tool.listTools 可见，5 个 action）
describe	5 个文档类型 / 14 个工程类型 / 5 个阶段，0 诊断
prepare	对插件自身：识别为 dsh-plugin，63 文件、15 条事实、8 节计划、14 条硬规则
verify	样例文档 PASS 18 / FAIL 0 / SKIP 0，引擎 check_brief.py
doctor	7 项全 PASS（python、资产、模板、目标、输出目录、扩展校验、断言编号）
scaffold	写出 doc-types/concise.js 并被注册表接受
测试	node test/run.mjs 20 passed（含双引擎逐条一致性、面板 catalog/run、多文档判卷解析）
面板	入口 = conversation.chat.commandview（key brief）+ 表单 = conversation.input.dock；一级工具行不再有按钮；Host 路由 project-brief/catalog、project-brief/run

依赖面：插件只 import node: 内置模块；python 缺失时扫描与判卷自动走内置 JS 引擎，判定序列与脚本一致（有测试守）。

从 GitHub 安装

git clone https://github.com/xxuucc/dsh-project-brief.git
plugin_manager action=install_bundle target=<clone 后的目录绝对路径>

与 skill 的关系

skills/project-brief 是规范与脚本的源头；本插件是它的执行体： 脚本逐字节复制到 assets/（改脚本请回 skill 改，再同步过来并跑一遍 node test/run.mjs）， SKILL.md 的章节规范被编译成 lib/builtins/sections.js 的数据，工作流被编译成 lib/builtins/stages.js。