交接文档 · Handoff

v0.4.0 开发交接快照 · 截至 2026-07-05

版本 · v0.4.0 状态 · 已发布 · main 全绿

一、一句话状态

MCP Server 已是功能完整、发布就绪的产品（11 工具 · 10 面板 · 43 评委 · 演化闭环 · webhook 入站）；v0.4.0 已发布，main 全绿零告警。代码侧无阻断的建设已收尾，剩余全部是需要你亲自解锁外部资源的项。

二、本次会话成果（11 个 PR，全部已合并）

PR	内容	commit
#28	v0.4.0 里程碑：MCP Server + 演化追踪 + 10 报告	—
#29	release.yml 自动用 CHANGELOG 生成 release notes	—
#30	4 份报告补真实公开来源（不编造）	—
#31	报告校验器建议告警清零（识别真实小节变体）	—
#32	修复 kimichat/qianxin 图表无限增长 bug	—
#33	报告渲染 QA 工具（无头浏览器检测图表）	—
#34	webhook 接收端（外部事件触发重审）	—
#35	本周周报（文档 + 网站页）	—
#36	周报模板 + 生成脚本	—
#37	MCP Server 完整面板系统（10 面板 / 43 评委）	—
#38	npm 发布 workflow	`91eb126`

测试：mcp-server 93 tests 全过 · 文档/网站：README / CHANGELOG / roadmap / agents / weekly 均同步。

三、产品现状：能用的东西 + 怎么用

1. MCP Server（`mba-mcp-server`）

装进 Claude Desktop / Cursor 等：

{ "mcpServers": { "mba": {
  "command": "npx", "args": ["-y", "mba-mcp-server@latest"],
  "env": { "ANTHROPIC_API_KEY": "sk-ant-..." }
}}}

11 工具：propose_audit · confirm_audit · get_status · fetch_report · list_audits · add_judge · subscribe_brand · trigger_evolution · list_subscriptions · unsubscribe_brand · get_delta_report
10 面板 / 43 评委：propose_audit({ brand, panel })，panel ∈ default / auto / luxury-en / vc-en / vc-cn / consumer-cn / ai-app-cn / edu-cn / cross-border / security-cn-global。可复现任何一份旗舰报告。
演化闭环：订阅 → 定时/事件/webhook 触发 → 增量重审（成本 ~$3→$0.4）→ delta 报告 → webhook/email 通知。
⚠️ 目前只能 clone 仓库本地跑；npx 需先发布（见 §四-1）。

2. Webhook 接收端（`mba-webhook-receiver`）

ANTHROPIC_API_KEY=... MBA_WEBHOOK_SECRET=... npx -p mba-mcp-server mba-webhook-receiver
# POST /webhooks/trigger { brand, event_type, event_summary } → 202

让外部系统（新闻监控/公关系统）主动推事件触发重审。需一个长运行部署位（小 VM / 容器 / systemd）。

3. 10 份公开报告

published/reports/* → 站点 mbabrand.com/reports/。全部含法律免责声明 + 真实公开来源。

4. 报告 QA 工具

node scripts/qa_report_render.mjs        # 发报告前跑，检测图表/渲染问题

5. 周报体系

python3 scripts/new_weekly.py new <日期> --milestone "..."   # 生成骨架
python3 scripts/new_weekly.py publish <日期>                  # md → 网页

四、⭐ 需要你操作的事项（外部资源解锁）

1. 把 MCP Server 发到 npm（让全世界能装）—— 最高价值

npmjs.com → Access Tokens → 生成一个 Automation token
仓库 Settings → Secrets and variables → Actions → 新增 NPM_TOKEN
Actions 面板 → Publish npm → Run workflow（可先勾 dry_run 彩排）
包名 mba-mcp-server 已确认空闲；当前版本 0.1.0。
发布是幂等的，workflow 会自动跑类型检查 + 93 测试 + 构建。

2. GitHub Release（已自动化，无需 token）

release.yml 用 GITHUB_TOKEN 即可。以后发版：改 metric-brand-auditor/SKILL.md 的 version: + 在 CHANGELOG 加对应小节 → Actions 跑 Release。

3. Wuying Pro（阿里云无影）→ 解锁两件事

25 位中文评委深化（Zhihu/微信/X 内容抓取，GetLink 需 Pro/Ultra）
keyword/news 自动触发器（P3-B-3，中文内容源）

升级后跑 python3 scripts/wuying/smoke_test.py 确认 GetLink 可用。

4. 沙箱网络放行 → vc-en 英文评委深化（P0-A）

paulgraham.com / a16z.com 等一手源目前 WebFetch 403。放行后可深化 paulgraham / bhorowitz / marcandreessen 三位。

五、代码地图（关键文件在哪）

packages/mcp-server/
  src/
    index.ts              MCP server 入口（stdio）
    receiver-main.ts      webhook 接收端入口
    server.ts             注册 11 个工具
    tools/                每个工具一个文件
    orchestrator/         Phase 2-5 编排 + 状态机 + 演化增量重跑 + 打分解析
    llm/
      prompts.ts          各阶段 prompt 模板
      personas.generated.ts   43 评委 persona（生成，勿手改）
      panels.generated.ts     10 面板映射（生成，勿手改）
    http/receiver.ts      webhook HTTP server
    notify/               webhook/email 出站通知
    store/                原子写文件存储 + 订阅存储
  scripts/generate-personas.py   从 perspectives/ + panels/ 重生成上面两个文件
  tests/                  93 tests

.github/workflows/
  release.yml             GitHub Release（GITHUB_TOKEN，已能用）
  publish-npm.yml         npm 发布（需 NPM_TOKEN）
  report-validation.yml   报告结构校验
  panel-validation.yml    面板 + API 校验

scripts/
  qa_report_render.mjs    报告渲染 QA
  new_weekly.py           周报生成
  generate-personas 见上

docs/                     01-13 设计文档 + weekly/ 周报 + 12-evolution-tracking
CHANGELOG.md              版本变更（有 Unreleased 段，下次发版现成）

重要约定：personas.generated.ts / panels.generated.ts 是生成产物，改评委/面板要改 perspectives/*/SKILL.md 或 panels/*.yaml，再跑 pnpm generate:personas 重生成。

六、解锁后建议的下一步

优先	前提	任务
1	`NPM_TOKEN`	发 `[email protected]` 到 npm
2	Wuying Pro	keyword/news 自动触发器（P3-B-3）—— 让演化系统真正自主
3	Wuying Pro	25 位中文评委深化 —— 提升审计专业度
4	网络放行	vc-en 3 位英文评委深化

七、给未来开发者 / 会话

# 跑测试
cd packages/mcp-server && pnpm install && pnpm test    # 93 tests
pnpm typecheck && pnpm build

# 重生成评委/面板数据
pnpm generate:personas

# 发报告前 QA
node scripts/qa_report_render.mjs

# 写周报
python3 scripts/new_weekly.py new <日期> && ... publish <日期>

分支：claude/sharp-turing-496l8b，已全部合并到 main。后续新工作从最新 main 起分支。
提交约定：commit 尾部带 Co-Authored-By + Claude-Session；不直接推 main；PR 合并前 CI 必须绿。
红线：anti-fabrication —— 报告结论/来源必须真实可核验，评委为 AI 模拟且明确标注，绝不编造 URL 或私下信息。

*本文档为本次开发会话的交接快照。产品状态截至 2026-07-05，v0.4.0。*