DeepInsight 项目章程

状态：已生效（项目元决策的根本记录） 作者：阿宝 + Claude 最后更新：2026-04-25 这是 DeepInsight 启动期"为什么这样设计"的根本记录。后续新增不在此处做：

新约定 → CLAUDE.md / docs/guides/CONTRIBUTING.md

新架构决策 → docs/architecture/adr/

任务令 / 责任田 / 探索期 / 业界参考 → 看板章节锚点（章程 § X.Y）会被其他文档引用，不要随意改章节号。

常用 prompt

8 人协作的"一句话指令"集合。所有约束（路径归档、commit 规范、不动他人目录等）都下沉到 CLAUDE.md / .claude/skills/ / git hooks 里——同事只需照搬下面的 prompt，agent 走完剩下的事。

本节是占位 + 首个样例，后续随着基础设施逐项落地会刷新内容。

1. 我是新人，怎么开始？

我是新人，怎么开始？

agent 会自动：① 检查环境（git config / Node / 看板依赖）；② 从 git config user.email 反查 docs/guides/TEAM.md 推断你的代号，不准就让你确认；③ 写 .claude/settings.local.json（注入 $DEEPINSIGHT_HANDLE）+ 从 explorations/_template/ 复制起步文件到 explorations/<代号>/ + 配 git hooks；④ 提示你关掉 Claude Code 再开一个让环境变量生效；⑤ 重开后说 "我要做一个 X 的 demo" 即可开工。

完全不需要记任何命令。只要 git clone 仓库 → 用 VS Code 打开 → 启动 Claude Code，剩下都靠这一句。接住的 skill：.claude/skills/onboard.md ✅（已落地）。

2. 出一个本地可看的洞察 demo

我要做一个洞察 demo，主题是 <在此填主题>。

agent 会自动：① 在 explorations/$DEEPINSIGHT_HANDLE/ 生成自包含的 index.html（双击可开）；② 用 mock 数据展示设想，不调真 LLM API（前期纯静态）；③ 不动 /web 主应用，也不动其他同事的 explorations/<other>/；④ 完成后告诉你打开命令。

接住的 skill：.claude/skills/explore-mode.md ✅（已落地）。前置：先用 prompt 1 跑过 onboard 设好 $DEEPINSIGHT_HANDLE。

0. 项目一页纸（Project One-Pager）

维度	内容
项目名	DeepInsight
目标	做"洞察分析"应用：用户以看报告为主，可上传 PDF、粘贴论文/博客链接，支持多模态输入与分析
形态	一期：Web；二期：手机 App（后续再设计）
团队	8 人，跨领域：研发范式、软件工程、系统设计、可靠性、测试
双重目标	①交付一个真实可用的产品；②作为"先进 code agent 协作"的沙盒 —— 探索多人+多 agent、spec 质量、skill 生命周期、subagent、工程规范
仓库	https://github.com/Boris-hbx/DeepInsight（已克隆至 `C:\Project\DeepInsight`，公开仓库，目前为空）

1. 已确认的决策

1.1 技术栈：方案 A

Next.js (App Router) + TypeScript + Tailwind CSS + shadcn/ui

理由：

前后端一体，8 人心智负担最小
单语言（TS）降低沟通成本
Anthropic SDK 有 TS 官方支持，多模态调用顺
React 组件未来可部分迁移到 React Native / Expo，为二期 mobile 留退路

多模态相关（待在 ADR 或 spec 中细化）：

PDF 解析（备选：pdf-parse / unpdf / Claude Files API 直接上传）
URL 抓取（备选：@mozilla/readability + jsdom / 外部 scraper API）
LLM：Anthropic Claude（多模态 + 长上下文适合长文档 insight）

1.2 仓库策略

单仓库 + /web 子目录，暂不引入 monorepo 工具（pnpm workspaces / Turborepo）
理由：8 人规模不值得；二期 mobile 出现时再升级，届时 /web 已是自然的子包
main 分支保护，禁止直推
分支命名：feat/<name>/<slug>、fix/<name>/<slug>、spec/<name>/<slug>
PR 必须关联一个 docs/specs/NNN-*.md
≥1 人 review + CI 绿灯才能合并

1.3 协作模式：人人端到端（everyone owns a slice）

每个人独立跑通一条垂直切片的全流程：

Proposal → docs/specs/NNN-*.md
Review：同事 comment；reliability / test 背景的人把检查项沉淀进 spec 模板
Build：feature 分支 + Claude / subagent 协作
Test：按自己 spec 的测试策略实现
Demo：合并后在团队 sync 演示

横向角色的杠杆点： reliability / test / SE 规范背景的人不做审批网关，做规范作者 —— 他们的产出是：

.claude/skills/ 下的 skill（可被全员自动触发）
docs/specs/TEMPLATE.md 里的检查项槽位
CI 中的自动化门禁

这样他们既有纵向的 slice 体验，又有横向影响力。

副轴补充（2026-04-23）：责任田（守护人制度）

主轴仍是垂直切片；副轴是 8 片横向责任田（Z-1 ~ Z-8），每人额外守护一片
守护人 ≠ 审批网关（保留上文禁区），= 规范/skill/CI 作者 + 默认 reviewer + 问题路由节点
8 片划分 + 认领规则 + 交接机制详见 docs/stewardship.md（真源），看板的「责任田」Tab 是视图
分配待开工会议认领，一人最多守护 2 片，Z-2 移动端当前体量小可搭售

1.4 Agent 协作元数据

commit message 约定标注 agent 参与程度（方便后续复盘"探索"数据）：

[human] 纯人类
[pair] 人机协作
[agent] agent 主导、人类 review

1.5 Git 身份

团队每人使用自己的 GitHub 账号邮箱（阿宝的是 baoxing2391@163.com）
待确认： 阿宝当前 shell 中 git global 为空，需本地配一次 git config --global user.email ...；或者 Claude 代为设置（方式待定）

1.6 项目运作看板

目的：让 8 人随时看到项目运作状态（特性切片进度、spec/ADR 索引、agent 协作度、运作手册）
形态：纯 HTML/CSS/JS 静态看板（继承 C:\Project\pm-dashboard 的风格，不引入 Next.js / React）
数据源：markdown 驱动 —— 自动解析 项目章程.md、docs/specs/*.md、docs/architecture/adr/*.md；git log 为辅（统计 commit 的 agent trailer）
部署：GitHub Pages（仓库已公开），地址 https://boris-hbx.github.io/DeepInsight/
⚠ 部署分支选择：用 gh-pages 分支 而不是 main 的 /docs 文件夹 —— 原因是 /docs 已被规划为开发文档目录（specs / ADR / guides），不能覆写。npm run deploy 会把构建产物推到 gh-pages 分支，GitHub Pages 自动发布（这是对上一轮"用 docs/ 文件夹"方案的修正）
两类内容：
- 运作手册（静态）：从本草稿 md 抽取，含一页纸、决策、spec 流程、目录规范、开放问题
- 实时状态（动态）：任务看板（按 8 位同事分卡片渲染 docs/task-board.md）、特性切片墙、agent 协作度统计、Skill/Subagent 注册表、ADR 索引、最近 demo
启动策略（分两波）：
- 第一波：空壳 + 运作手册渲染，让 8 人能看到"规则怎么跑"
- 第二波：等有真实 spec/commit 后，状态面板自动填充
原则：草稿 md 是唯一真源，看板是视图；改 md → npm run build 重渲染，一致性由工具保证

2. 目录规范（待评审）

DeepInsight/
├── CLAUDE.md                   # 项目级 Claude Code 指引
├── README.md                   # 项目简介 + 快速开始
├── 项目章程.md            # 本文档（实施后归档或删除）
├── 项目章程.html          # 本文档的渲染版（浏览器阅读用）
├── package.json                # 看板构建脚本依赖（轨道 B）
├── .gitignore
├── docs/                       # 开发文档（仓库内阅读；不走 GitHub Pages）
│   ├── task-board.md           # 任务看板真源（T-xxx 令 + 接令回写）
│   ├── architecture/
│   │   └── adr/                # Architecture Decision Records（NNNN-title.md）
│   ├── specs/                  # 特性 proposal（NNN-slug.md）
│   │   └── TEMPLATE.md
│   ├── guides/                 # 贡献指南、开发手册
│   │   └── CONTRIBUTING.md
│   └── assets/
│       ├── screenshots/        # UI/bug 截图（YYYY-MM-DD-desc.png）
│       └── diagrams/           # 架构图/流程图源文件
├── dashboard/                  # 运作看板源码（与 /web 解耦）
│   ├── index.html
│   ├── assets/
│   │   ├── style.css
│   │   └── main.js
│   └── data.json               # 构建产物（gitignore，每次 build 生成）
├── scripts/
│   └── build-dashboard.js      # 扫描 md + git log → data.json → dist/
├── web/                        # Next.js 应用
├── .claude/                    # 项目级 Claude Code 配置
│   ├── agents/                 # 项目 subagent 定义
│   ├── skills/                 # 项目 skill
│   └── settings.json           # 共享的权限、hook
└── .github/
    ├── PULL_REQUEST_TEMPLATE.md
    └── workflows/              # CI（后续添加）

命名约定：

spec：docs/specs/NNN-short-slug.md，NNN 单调递增（001 起）
ADR：docs/architecture/adr/NNNN-title.md（4 位，业界惯例）
截图：docs/assets/screenshots/YYYY-MM-DD-description.png
图表源文件：docs/assets/diagrams/<name>.{drawio,excalidraw,puml}
看板发布：gh-pages 分支（GitHub Pages 自动识别），由 npm run deploy 推送 —— 不进 main 分支

3. 实施步骤（两条并行轨道）

分两条并行推进：轨道 A（应用本体）仍是治理 → 技术栈 → 业务脚手架三层；轨道 B（运作看板）独立成线，与 A 无阻塞关系。轨道 B 先出成果，能让 8 人立刻看到"运作规则"。

轨道 A：应用本体

A1 第一轮（治理层，本次）

README.md
.gitignore（Node/Next.js + IDE + OS + dashboard/data.json + dist/）
CLAUDE.md
docs/specs/TEMPLATE.md（含 reliability/test checklist 槽位）
docs/guides/CONTRIBUTING.md（分支、PR、review 流程）
docs/architecture/adr/0000-record-architecture-decisions.md（采纳 ADR）
.github/PULL_REQUEST_TEMPLATE.md
占位 .gitkeep：docs/assets/screenshots/、docs/assets/diagrams/、.claude/agents/、.claude/skills/

A2 第二轮（技术栈）

web/ 目录 Next.js 脚手架（TS + Tailwind + shadcn/ui + Anthropic SDK）
基础 .eslintrc / prettier / tsconfig 约定
首批 ADR：多模态后端选型、LLM 调用封装位置、状态管理（待决策 — 见下方问题）

A3 第三轮（业务脚手架）

第一个垂直切片：用户上传一份 PDF → 得到洞察摘要
.github/workflows/ci.yml：lint + typecheck + test

轨道 B：项目运作看板

B1 第一波（空壳 + 运作手册，可立即启动）

package.json（依赖：gh-pages、gray-matter、marked、simple-git）
dashboard/index.html（布局骨架：顶栏 + 运作手册 + 切片墙占位 + 协作度占位）
dashboard/assets/style.css（暗色系 + CSS 变量，继承 pm-dashboard 风格）
dashboard/assets/main.js（读 data.json 渲染）
scripts/build-dashboard.js：从 项目章程.md 提取章节 → data.json
npm run serve 本地预览；npm run deploy 推到 gh-pages 分支
GitHub 仓库 Settings → Pages，source 切到 gh-pages 分支
首次部署验证地址 https://boris-hbx.github.io/DeepInsight/

B2 第二波（真实状态面板填充，依赖 A1 产出）

扫描 docs/specs/*.md 生成切片墙（按负责人分列）
扫描 docs/architecture/adr/*.md 生成 ADR 索引
git log 解析 [human]/[pair]/[agent] trailer 统计
.claude/skills/ 扫描生成 skill 注册表
可选：最近 demo 流（从 merge commit 提取）

4. 业界最佳实践

由 Claude agent 于 2026-04-23 联网调研产出。所有链接点进去即可验证。

4.1 参考产品与开源项目

Morphic — Next.js + AI SDK + shadcn/ui 的 "answer engine"，和我们的栈几乎同构。值得借鉴：models.json 统一多 provider 配置、Tavily/SearXNG/Exa 可切换的检索抽象、Generative UI 流式组件。
Vercel AI Chatbot — 官方模板，AI SDK v6 统一 25+ provider，RSC + Server Actions 模式。可直接 fork 作为脚手架，但它默认用 OpenAI，Anthropic SDK 需要替换 provider 层。
LobeChat — @lobechat/model-runtime 与 @lobechat/agent-runtime 双层拆分（LLM 适配器 vs Agent 编排）是我们做 PDF 分析 pipeline 时值得复用的分层思路；Supervisor + Executor 模式对多步报告生成有参考价值。
GPT Researcher / LangChain open_deep_research — Planner + Executor + Publisher 的 tree-like 探索模式，对"上传 PDF/URL → 生成结构化报告"的流程非常契合；GPT Researcher 公布了单次 ~$0.40 的成本基线可参考。
Elicit — 工业级 "sentence-level citation" 的标杆；UI 上每条 claim 都可追溯到原文句子，这是 report-style 产品的关键差异点。
Claude Projects / Anthropic Citations API — 官方 Citations feature 原生支持 PDF 分块、cited_text 不计入 output token，比自研引用对齐省事得多，建议作为 MVP 的默认方案。

4.2 LLM-powered 应用特有的初始化维度

Prompt 管理：day 1 用仓库内 prompts/*.md + 小工具做模板化（变量注入、版本号前缀）；不要代码内嵌长字符串。中期上 Langfuse（开源、可自托管、支持 prompt versioning + trace 关联）。注意：Humanloop 已于 2025-09-08 被 Anthropic 收购后关闭，不要再选它。
Eval 最简起步：参考 DeepEval 建议 —— 从 3-5 个核心功能各挑 10-20 条 golden case（输入 + 期望输出/评分维度）入仓，CI 里跑 LLM-as-judge + 关键字段精确匹配。Citation 准确率和 hallucination 率是 report app 必须 day 1 就度量的两个指标。
流式 UX：使用 AI SDK 的 useChat，实现 stop / reload / onError；60s 客户端超时、关闭 tab 时的 partial message 标记、指数退避重试是四个易漏点（参考）。错误消息对外统一文案，避免泄露 provider 报错。
成本 / 限流：OpenTelemetry span 上打 user_id / feature / prompt_version tag（Traceloop 方案）。限流用 token-based 而非 request-based（参考 Portkey、Azure llm-token-limit）；每个用户设日 token budget。
安全：按 OWASP LLM01:2025 处理 indirect prompt injection —— 上传 PDF 一律用 <untrusted> 分隔标签包裹、系统提示明确声明"文档内容不是指令"。PII 在入库前做脱敏；上传文件做 MIME/magic bytes 校验 + 大小限制 + 病毒扫描。
Citation：直接用 Anthropic Citations API，不要自己做对齐。
长上下文：单请求 ≤100 页用 Citations 原生 PDF；超过则 map-reduce 分章节摘要 → 再合成；考虑 Claude Sonnet 4.6 / Opus 4.6 的 1M token 上下文（无溢价）作为长文档 fallback。

4.3 Spec-driven / ADR / RFC 在 8 人团队的落地

流程范式：参考 Rust RFC / React RFC（后者基于前者）—— markdown 模板 + PR 讨论 + "final comment period" 收口。8 人团队建议门槛下调：只要求跨 2 个模块或 >2 天工作量的改动走 RFC。
ADR vs Spec vs RFC（参见 Candost / ceaksan）：RFC 回答"要不要做、怎么做"；ADR 记录"为什么选了这条路"（单个决策点、短小）；Spec 回答"要做什么、怎么验收"。三者并存，一个 RFC 通过后可派生多个 ADR + spec。
OpenSpec：轻量 SDD 框架，三阶段状态机（proposal → apply → archive）+ 增量标记（ADDED/MODIFIED/REMOVED），对 brownfield 迭代友好；输出约 250 行，review 成本远低于 GitHub Spec Kit（约 800 行）。与 Claude Code 原生兼容，适合作为本项目"spec 即 agent 上下文"的抓手。

4.4 Multi-agent / AI 协作治理（新兴领域，资料有限）

Claude Code Agent Teams（实验性，CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS）：lead + 3-5 teammate 的共享 task list 模式，适合 "research + review + cross-layer 改动"。官方三原则：最小权限、可逆优先、高风险处人工卡点，配合 --allowedTools 白名单。
Commit 归因：Claude Code 默认写 Co-Authored-By: Claude <noreply@anthropic.com> trailer，GitHub 会展示 co-author。社区有争议（反对观点），建议团队统一用专用 Assisted-By: 或 AI-Agent: trailer + 模型版本，而非复用 Co-Authored-By；可借 git-ai 类工具。
Skill / prompt / agent 版本管理：参考 anthropics/skills 官方仓库约定 —— 每个 skill 一个目录 + SKILL.md (YAML frontmatter)。Anthropic 的 **skill-creator eval 模式**把 eval 结果绑到具体版本（v1.1 vs v1.2 盲测 A/B），值得照搬到我们自己的 prompt/agent review 流程。
未找到权威资料：公开的"多人 + 多 agent 在同一仓库的分工冲突解决手册"几乎没有，属于我们可以贡献经验的空白区。

4.5 对 DeepInsight 的具体建议（尚未纳入我们决策的维度）

Day 1 就把 Citations API 作为默认后端，UI 组件里每一段文字强制可点到原文 span，避免后期翻修。
建 evals/ 目录入仓，最小化 20 条 golden（含对抗性 PDF prompt injection 样本 3-5 条），CI 拦截 citation 准确率 / injection 成功率回归。
Prompt/Skill/Agent 都当 code review：PR 模板加上"prompt 变更需附 A/B eval diff"一栏，对齐 Anthropic skill-creator 的做法。
把 "AI 参与度" 做成结构化元数据（commit trailer + 自建 .ai-meta.json），为团队的治理实验留下可分析的时间序列，而不是自由文本。
多 agent 并行时启用共享 task list 而非自由分叉，并把 "高危操作需人工 approve" 列为不可绕过的 hook，避免 8 人 × N agent 的 race condition。

5. 体验方式与部署（前期简化版）

决策日期：2026-04-23

前期 MVP 阶段区分两个对象的部署策略：

应用本体（/web）：纯本地开发，不部署、不做登录。

每人 clone 仓库，在自己的 feature 分支上开发
cd web && npm run dev 起本地 dev server（localhost:3000，Next.js 原生热重载）
自己验证 OK → 提 PR → review → 合入 main
合并后的效果：大家 pull 最新 main 自己本地跑

运作看板（/dashboard）：走 GitHub Pages（gh-pages 分支）。

npm run deploy 自动推送，GitHub Pages 自动发布
只读、纯静态、无用户数据、无登录需求（因此没有安全负担）
配置细节见 1.6

应用本体推迟到后续的事项：

统一部署（涉及平台选型：Vercel vs Fly.io）
登录 / 权限 / 鉴权
PR preview 环境
CI/CD 流水线（初期只做本地 lint + typecheck，不设云端 CI 也可先行）
团队 billing / 共享 API key

Anthropic API Key 管理（当前阶段）：

每人自己去 console.anthropic.com 申请个人 API key
放在各自本地 web/.env.local（必须 .gitignore，禁止提交）
用自己的 billing，dev 量很小，个人承担
团队 workspace + 统一 billing 的方案留到"需要部署预览环境"或"做 eval 消耗大"时再引入

澄清（记录给全员）：

Claude Code 订阅（每人各自的）≠ DeepInsight 应用运行时用的 Anthropic API Key（sk-ant-...）。前者是大家用的开发工具，后者是我们要构建的 app 内部调用 Claude 的凭证，两者账号体系独立。

6. 开放问题

Git 身份处理：阿宝自己执行 git config --global，还是 Claude 代设？
第一个垂直切片选什么？建议是"上传 PDF → 摘要"最简化路径，你们怎么看？
CI 提供商：GitHub Actions（默认）？要不要同时接本地 pre-commit hook？
8 人的身份：需不需要一份 docs/guides/TEAM.md 记录每人背景与关注方向，方便 agent 在评审时引用？
Skill 与 Subagent 的生命周期治理（这是你们明确要探索的点）：
- 谁有权 merge 一个新 skill/agent？
- 如何评估 skill 的"质量"？
- skill 版本怎么管？
- 这块要不要单独写一份 docs/guides/agent-governance.md 作为 spec 草稿？
Eval 体系：LLM 输出的质量怎么评估？要不要一开始就引入（哪怕只是简单的 snapshot test）？
成本观测：LLM 调用费用监控从第几轮开始考虑？
Prompt 管理：prompt 和代码的关系（文件内嵌 / 独立 .md / 专用工具）？

7. 变更日志

2026-04-23 初稿（阿宝 + Claude 对话 1~4 轮结果沉淀）
2026-04-23 补充第 4 节"业界最佳实践"（agent 联网调研）
2026-04-23 新增第 5 节"体验方式与部署（前期简化版）"：确认 MVP 阶段纯本地开发，API key 每人自用，部署/登录/团队 billing 推迟
2026-04-23 新增 1.6 "项目运作看板"：markdown 驱动的静态看板 + GitHub Pages；部署改用 gh-pages 分支（避免与 /docs 开发文档目录冲突 —— 修正上一轮建议）；目录规范新增 dashboard/、scripts/、package.json；实施步骤重组为 A/B 两条并行线；第 5 节区分"应用本体"与"运作看板"的部署策略
2026-04-23 完成 A1 治理层：README.md、CLAUDE.md、docs/specs/TEMPLATE.md、docs/guides/CONTRIBUTING.md、docs/architecture/adr/0000-record-architecture-decisions.md、.github/PULL_REQUEST_TEMPLATE.md + 4 个 .gitkeep 占位全部落地。开放问题 #1（Git 身份）已通过 per-repo config 解决
2026-04-23 A2 脚手架 2/3 完成：web/ 建立（Next.js 16 + React 19 + Tailwind v4 + shadcn/ui + @anthropic-ai/sdk + Prettier）；eslint.config.mjs 由 create-next-app 生成，tsconfig.json 默认 strict。首批 ADR（多模态后端 / LLM 调用封装 / 状态管理）待阿宝拍板
2026-04-23 新增 任务看板（docs/task-board.md + dashboard "任务看板" Tab）：参考 ergouPM 的 T-xxx 令规，适配"人人端到端、无中央 PM"模式；首批 10 条令已按 8 位同事（阿勇/阿伟/阿杰/阿智/阿栋/阿隽/阿锋/阿宝）分配（治理/infra/ADR/特性 4 类），可在看板上直接看到每人在跟哪些令
2026-04-23 新增 责任田（docs/stewardship.md + dashboard "责任田" Tab）：副轴守护人制度，共 Z-1 ~ Z-8 八片（前端 UX / 移动端 / LLM 调用层 / 数据 pipeline / 运行时保护 / 测试 & Eval / Agent 基建 / DevEx + 看板），守护人 ≠ 审批网关，分配待开工会议认领；同时配 Claude Code Stop hook 与 GitHub Actions workflow，改 md 自动重建/部署看板