dommaker · github-actions · Sep 18, 2026 · Sep 15, 2026 · Sep 15, 2026 · Sep 15, 2026
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -23,7 +23,7 @@ jobs:
         run: pnpm install
 
       - name: Build
-        run: pnpm build
+        run: pnpm build && pnpm build:npm
 
       - name: Test
         run: pnpm test

diff --git a/.gitignore b/.gitignore
@@ -4,6 +4,7 @@ node_modules/
 # Build output
 dist/
 build/
+dist-npm/
 
 # API 前端构建产物落盘（apps/api/frontend/dist 由 prod/deploy.sh 同步，
 # 历史手工拷贝的 stale 副本以 dist.stale-* 隔离；整个目录不入库）
@@ -62,6 +63,12 @@ docs/*
 !docs/adr/
 # docs/visual-reports/ 豁免——#390 决议：截图 diff 报告入 git 作改版验收凭据（#391）
 !docs/visual-reports/
+# docs/specs/ui/style-guide.md 豁免——样式规范是唯一权威来源，须入 git 评审/回溯（批次 I-1 治理人闸当场过，2026-09-16）；其余 spec 源文件维持忽略
+!docs/specs/
+docs/specs/*
+!docs/specs/ui/
+docs/specs/ui/*
+!docs/specs/ui/style-guide.md
 
 # Scratch workspace (ignored)
 .scratch/
@@ -88,9 +95,9 @@ e2e/.auth.json
 CLAUDE.md
 .claude/
 
-# Runner worktree artifacts (regenerated per worktree at runtime;
-# committing them breaks per-worktree regeneration — runner-execution only
-# writes CACHE_PREFIX.md when absent, and worktrees inherit tracked files)
+# Runner worktree artifacts (regenerated per worktree at runtime; committing them
+# breaks per-worktree regeneration, and worktrees inherit tracked files).
+# 两条写方随 #562 删除，保留规则只为兜住历史 worktree 里的残留产物。
 CACHE_PREFIX.md
 .prompt.md
 

diff --git a/.harness/config.yml b/.harness/config.yml
@@ -1,3 +1,3 @@
 preset: standard
 harness:
-  version: 1.7.0
+  version: 1.8.0
diff --git a/AGENTS.md b/AGENTS.md
@@ -14,6 +14,7 @@
 | `.harness/` | harness 配置与运行时状态 |
 | `apps/` | monorepo 应用：api、web |
 | `bin/` | 可执行入口/脚本 |
+| `dist-npm/` | — |
 | `docs/` | 项目文档 |
 | `node-compile-cache/` | — |
 | `packages/` | monorepo 共享包：studio-agent、studio-audit、studio-capability、studio-notification、studio-shared、studio-skill、studio-spec |
@@ -46,9 +47,11 @@ pnpm start  # 启动生产服务
 
 > 本段手写，增删改走段末「治理变更流程」。依据：docs/adr/2026-08-21-agent-docs-three-kinds.md（内容三分）+ 2026-08-21-agent-docs-placement-model.md（落点模型），2026-08-21 自 CLAUDE.md 迁入（#300/#303）。
 
+- 数据目录契约：`docs/architecture/data-directory-contract.md` 是 `~/.studio` 数据区布局/可改纪律/变更纪律/版本迁移的唯一正本；布局变更须先修订契约（出处：#570 / docs/plans/2026-09-npm-local-form.md §7.4，治理人闸 2026-09-16 当场通过）。
+
 ## Governance Rules
 <!-- HARNESS_CONSTRAINTS_START -->
-<!-- version: 1.7.0 -->
+<!-- version: 1.8.0 -->
 ### Iron Laws (违反将阻断)
 - **no_completion_without_verification**: 在声明任务完成前，必须重新运行新鲜的验证命令——受改动影响的测试（vitest run --changed origin/master）+ type check，使用新鲜的输出作为完成证据，不得复用旧结果。全量测试由 CI / 发布流程兜底。
 - **incremental_progress**: 一次只处理一个任务。改动涉及多个模块、超过 100 行、或影响多个文件时，必须拆分为小步骤分步执行，每步有独立 checkpoint 可回滚。不要试图一次性完成所有改动。
@@ -168,6 +171,7 @@ pnpm start  # 启动生产服务
 | `apps/api/src/modules/mcp` | MCP（Model Context Protocol）模块 — 将 Studio 系统能力暴露为 MCP tools，供 Agent 和 UI 共享调用。 |
 | `apps/api/src/modules/monitoring` | 负责聚合 Agent Network 的监控指标，包括 Agent 摘要、统计信息、飞轮指标（M1）和封装开销（M2），通过 HTTP 路由对外暴露。 |
 | `apps/api/src/modules/notifications` | 提供通知相关的 API 路由，包括获取通知列表、查询未读数量、标记单条已读和标记全部已读，作为后台消息通知模块的 HTTP 接口层。 |
+| `apps/api/src/modules/notify-channels` | 通知渠道配置（#525 P2-6，决策 #516 项⑦⑧）：服务端配置存储 + 读写 API + ClawBot（iLink 协议）内嵌轻量直连。/settings「通知渠道」配置区的服务端支撑——#434 死配置的「复活成真功能」版... |
 | `apps/api/src/modules/outbound-notify` | 本模块提供基于 Discord 的通知发送服务，支持多种任务与会议相关通知类型。内部封装了对 discordNotifier 的调用，并通过 eventBus 将通知事件发布到消息总线。还暴露 HTTP 路由供内部模块通过 POST... |
 | `apps/api/src/modules/pmo` | 项目管理办公室（PMO）：OKR 管理 + 项目 CRUD + 交付守卫。PMO 是链条脊椎：id = 分支名、需求文档挂载点、状态 = WU 汇总 + 证据台账、交付策略挂在项目上。统一编号 PMO-<n>。 |
 | `apps/api/src/modules/projects` | Project Discovery（AC-D1 + AC-D3）：发现已注册的工程（repo）信息并对外提供查询 API，供频道默认工程、WorkUnit 工程绑定等流程使用。 |
@@ -176,12 +180,12 @@ pnpm start  # 启动生产服务
 | `apps/api/src/modules/role-memory` | 角色记忆存储服务：per-role 目录落数据区（经 studioPath()），三件套--MEMORY.md 索引 + topics/*.md topic 正文 + draft.jsonl append-only 草稿区。role-... |
 | `apps/api/src/modules/skills` | skills 模块负责技能（Skill）的完整生命周期管理，包括基于文件的技能元数据存储（SkillStore）、技能目录扫描与加载（manifest-loader）、基于描述的技能匹配（skill-selector）、从 WorkU... |
 | `apps/api/src/modules/specs` | 提供 Specs 模块的 HTTP API 路由，包括变更分析、变更历史查询和门禁验证（待实现）。遵循 SP-002 变更分级流程，通过调用外部 SDK 中的服务处理 Spec 变更相关的业务逻辑。 |
-| `apps/api/src/modules/transcripts` | transcript 归档器（#97，#88 子票）：把会话原文落盘到数据区（经 studioDir()/studioPath()），供三个消费方共用——#99 WU 收尾批量提取（要全文）、handoff 摘要（要对话）、#85 执... |
+| `apps/api/src/modules/transcripts` | transcript 归档器（#97，#88 子票）：把会话原文落盘到数据区（经 studioDir()/studioPath()），供四个消费方共用——#99 WU 收尾批量提取（要全文）、handoff 摘要（要对话）、#85 执... |
 | `apps/api/src/modules/triage` | 实现错误的分类（triage）与严重度评估，提供策略路由（auto_retry / manual_fix / escalate / ignore），支持开发者错误和系统级事件的分类。 |
 | `apps/api/src/modules/triggers` | Trigger 子系统（AS-026，3.28c-4）：SCHEDULE（cron）+ EVENT（EventBus）两类条件的触发器调度与持久化，动作包括 CREATE WorkUnit / UPDATE / EXECUTE。系统默... |
 | `apps/api/src/modules/workspaces` | 本机 Workspace 记录的自动注册与查询（只读 list/get + 删除）、CLI 运行时清单扫描。Token 管理已随 #481 退役删除。 |
 | `apps/api/src/modules/workunit` | WorkUnit 核心域: 任务单元 CRUD、认领与状态机; F5 双向沟通的 NEED_INPUT 挂起/恢复与超时提醒。 |
-| `packages/studio-agent` | Sub-agent 的完整生命周期管理：创建隔离 worktree → spawn Claude Code → session loop 监控 → 完成判定。 |
+| `packages/studio-agent` | Sub-agent 的完整生命周期管理：创建隔离 worktree → 传播 harness 配置 → spawn provider CLI（单 session）→ stream-json 解析与事件发射。完成判定/状态机不在本包，由... |
 | `packages/studio-audit` | 提供审计日志的记录、查询、统计与导出功能。通过 AuditService 进行持久化日志操作（JSONL 存储）。 |
 | `packages/studio-capability` | 本目录负责能力管理（CapabilityService）。CapabilityService 提供能力的 CRUD、同步、统计，并基于 FileStore JSON 文件存储实现（替代 Prisma）。 |
 | `packages/studio-notification` | 本目录提供 studio-notification 包的核心代码，包含通知的创建、查询、标记，服务层基于 FileStore 实现持久化通知管理。 |

diff --git a/CAPABILITIES.md b/CAPABILITIES.md
@@ -1,6 +1,6 @@
 # CAPABILITIES.md
 
-> 最后更新: 2026-09-15
+> 最后更新: 2026-09-17
 
 ---
 
@@ -16,7 +16,7 @@
 
 | src | packages/studio-shared/src/ | Studio Event Bus — 替代 Redis pub/sub（2026-05-08） |
 | auditor-types | packages/studio-shared/src/harness/auditor/auditor-types.ts | Auditor ↔ 其他角色协议定义（BP-013 + BP-014） |
-| hooks | packages/studio-shared/src/harness/hooks/ | Agent Execution Phase Hooks |
+
 | harness | packages/studio-shared/src/harness/ | Constraint Prompt Injection — 将 harness 约束的前置声明注入 Agent prompt |
 | runtime | packages/studio-shared/src/harness/runtime/ | Harness Runtime Bootstrap — Phase 2 迁移 |
 
@@ -275,4 +275,7 @@
 | NotifyChannelsSection | apps/web/src/components/settings/NotifyChannelsSection.tsx | 通知渠道 section（#525 P2-6）：企业微信群机器人 webhook + ClawBot（个人微信）扫码绑定 + 浏览器通知总开关。 |
 | wecom-client | apps/api/src/modules/notify-channels/wecom-client.ts | 企业微信群机器人 markdown 发送唯一出口（#525 review 收口）： |
 | ChannelStreamBody | apps/web/src/components/channel/ChannelStreamBody.tsx | 频道消息流结构组件（#531，架构评审 2026-09-14 候选 3）：消费 useChannelStream 产物， |
+| ChannelMessageEnv | apps/web/src/components/channel/ChannelMessageEnv.tsx | 频道消息环境（#547，架构评审 2026-09-15 候选 B3，grilling 已决）： |
+| ApproveDialogShell | apps/web/src/components/ui/ApproveDialogShell.tsx | ApproveDialogShell — 审批弹窗公共壳（docs/plans/2026-09-web-ux-optional-fixes.md Step 3， |
+| PlanDirectionCard | apps/web/src/components/channel/PlanDirectionCard.tsx | PlanDirectionCard — #567：方向锁定接力卡（plan 一脉会话内方向人闸，裁决轮前置环节） |
 | mockMatchMedia | apps/web/src/test/mockMatchMedia.ts | #395：jsdom 无 window.matchMedia 实现——按给定视口宽度求值 (min|max)-width 媒体查询， |
diff --git a/apps/api/bench/claim-latency.ts b/apps/api/bench/claim-latency.ts
@@ -12,8 +12,9 @@
  *   特征词触发 B2 守卫——认领后立即关闭，不起 LLM 会话、不烧 token）：
  *   B1 拾取延迟：建 unassigned WU（指名本 role）→ 轮询 index 拿 claimedAt，N 轮随机相位；
  *      同时记录 getIndex 调用时刻，验证 workunit.created EVENT 触发的 observe 是否带来认领。
- *   B2 事件唤醒延迟：blocked WU（assignee=实例）进入 lastActiveWuIds 后发人类消息，
+ *   B2 事件唤醒延迟：blocked WU（assignee=实例）就绪且 loop 进入 idleSleep 后发人类消息，
  *      测量 message_sent publish → 下一次 observe(getIndex) 的时延。
+ *      （2026-09-16 唤醒放宽：不再等 lastActiveWuIds，该派生缓存机制已删——唤醒只放行不裁决）
  */
 import fs from 'node:fs';
 import path from 'node:path';
@@ -187,7 +188,8 @@ async function main(): Promise<void> {
 
   // B2：channel.message_sent 唤醒延迟
   console.log('\n── B2: 人类消息 → 唤醒 idle sleep → 下一次 observe ──');
-  // 建 blocked WU 挂本实例，等它进入 lastActiveWuIds（observe 每 ≤15s 刷一次）。
+  // 建 blocked WU 挂本实例。2026-09-16 唤醒放宽后不再等 lastActiveWuIds（机制已删，
+  // 唤醒只放行不裁决）——只需等 loop 进入 idleSleep。
   // scope 必须带 test 特征词：唤醒后 loop 会真的拾取该 WU 起会话——B2 守卫拦在
   // prompt 组装前直接关闭，防误烧 token（2026-09-12 首跑教训：无 test 词的 scope
   // 被唤醒的 loop 当真任务 spawn 了真实 CLI 会话）。
@@ -197,17 +199,14 @@ async function main(): Promise<void> {
   });
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   const seam = loop as any;
-  const regDeadline = Date.now() + 20_000;
-  while (!seam.lastActiveWuIds?.has(blockedWu.id) && Date.now() < regDeadline) {
-    await new Promise(res => setTimeout(res, 100));
-  }
-  if (!seam.lastActiveWuIds?.has(blockedWu.id)) {
-    console.log('B2 SKIP: blocked WU 20s 未进入 lastActiveWuIds');
-  } else {
-    console.log('[bench] blocked WU 已进入 lastActiveWuIds，loop 处于 idleSleep');
+  {
     // 等 loop 确实进入 idleSleep（wakeIdle 挂起）
     const idleDeadline = Date.now() + 20_000;
     while (!seam.wakeIdle && Date.now() < idleDeadline) await new Promise(res => setTimeout(res, 50));
+    if (!seam.wakeIdle) {
+      console.log('B2 SKIP: loop 20s 未进入 idleSleep');
+    } else {
+    console.log('[bench] loop 处于 idleSleep');
     const wakeLat: number[] = [];
     for (let i = 0; i < 3; i++) {
       // 等回 idleSleep
@@ -233,6 +232,7 @@ async function main(): Promise<void> {
       await new Promise(res => setTimeout(res, 3_000));
     }
     if (wakeLat.length > 0) console.log(`B2 唤醒延迟: ${summary(wakeLat)}`);
+    }
   }
 
   loop.stop();

diff --git a/apps/api/package.json b/apps/api/package.json
@@ -2,9 +2,6 @@
   "name": "@dommaker/studio-api",
   "version": "0.1.0",
   "private": true,
-  "bin": {
-    "studio": "src/cli/studio-cli.ts"
-  },
   "scripts": {
     "dev": "STUDIO_HOME=${STUDIO_HOME:-$HOME/.studio-dev} tsx watch src/index.ts",
     "build": "tsc",
@@ -13,7 +10,7 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@dommaker/harness": "^1.7.0",
+    "@dommaker/harness": "^1.8.1",
     "@dommaker/studio-agent": "workspace:*",
     "@dommaker/studio-audit": "workspace:*",
     "@dommaker/studio-capability": "workspace:*",

diff --git a/apps/api/src/app.ts b/apps/api/src/app.ts
@@ -106,6 +106,8 @@ export async function registerRoutes(): Promise<void> {
       '/mcp/health',       // MCP health check
       '/mcp/sse',          // MCP SSE transport endpoint
       '/mcp/messages',     // MCP SSE message endpoint
+      '/mcp/external/sse',      // #566: 外部只读 SSE 入口（钉死 external 角色）
+      '/mcp/external/messages', // #566: 外部只读 SSE 消息端点
     ]);
     const optAuth = optionalAuth();
     app.use('/api/v1', async (req: any, res: any, next: any) => {

diff --git a/apps/api/src/cli/CONTEXT.md b/apps/api/src/cli/CONTEXT.md
@@ -0,0 +1,28 @@
+# apps/api/src/cli — Studio CLI 入口与命令域
+
+## 职责
+
+`studio` 命令的入口/分发（studio-cli.ts）与各命令域实现。两类服务启动路径：
+
+- `studio run web`（run-web.ts，#571）：npm 本地形态一体起服务总入口——API + 托管已构建 web dist + 首启检测块 + 端口动态顺延，前台进程 Ctrl-C 即停。
+- `studio up`（server.ts）：服务器形态启动（systemd 托管场景），原样保留。
+
+## 核心导出
+
+- `studio-cli.ts`：入口/分发/帮助文本；`run web [--port <n>]` 动词。
+- `run-web.ts`：`studioRunWeb()`——启动链：ensureDataDirs/ensureDaemonSecrets → 端口解析 → 首启面板 → preflight（存储探针 + frontend dist）→ ensureDefaults → `await import('../index.js')`。数据区迁移钩子接入点（#572）在其 preflight 之前。
+- `bootstrap.ts`：ensureDataDirs / ensureDaemonSecrets（env > .daemon/ 文件 > 生成落盘）/ probeStorageWritable；run web 与 up 共用。
+- `port-probe.ts`：probePortFree（net 模块探测，跨平台不走 lsof）/ resolvePort（默认 3001 起顺延上限 +100；显式 --port/PORT 占用即拒启）/ parsePortFlag / explicitPortFromEnv。
+- `first-run-panel.ts`：buildFirstRunPanel()——Node 版本对 engines>=20、cli-scanner 全 provider 探测结果、数据根、实际监听地址；零 provider 只提示不阻断。
+- `mcp-install.ts`（#566 P3）：`studio mcp install <agent> [--url] [--print] [--uninstall]`——把对外只读 MCP 入口（/api/v1/mcp/external/sse）幂等合入 agent 用户级配置（claude `~/.claude.json` / kimi `~/.kimi-code/mcp.json` / opencode `~/.config/opencode/opencode.json`，均只动 `studio` key、写前 .bak 备份、JSON 损坏拒写）；URL 缺省探测 3001 /mcp/health，不通报错提示 --url；codex 不支持 SSE 报错（Q2 不架 mcp-remote 桥）。
+- `skill.ts` + `skill-validate.ts`（#568）：`studio skill validate/export/install` 流动三件套——纯本地文件操作（daemon 离线可用，与走 HTTP 的 `studio skill list` 分流于 studio-cli.ts `case 'skill'`）；validate 规则 = 布局 + frontmatter（name≠目录名为 error，description/triggers 缺为 warning）；export = 目录拷贝 + `PROVENANCE.json` 边车（contentHash 复用 `hashSkillDir`，脱敏不写绝对路径）；install 与内置正本同名硬拒绝（保护 seed hash 升级通道），冲突/no-op/--force 三态，不碰 `.builtin-hashes.json` 与 `skills-index.json`。
+
+## 注意事项
+
+- **npm 单包形态 = esbuild bundle**（`scripts/build-npm.mjs` → `dist-npm/`，根 package.json files 白名单 `bin/studio` + `dist-npm`）：workspace 包代码全部内嵌，npm 依赖保持 external（= 根 dependencies，metafile 校验内嵌零 node_modules）。`bin/studio` 薄入口：bundle 存在则 import，否则 monorepo fallback 到 tsx 跑源。
+- **两个 bundle 相对路径约定**：frontend dist = `<bundle>/../frontend/dist`（与 app.ts:133 同表达式）；内置 skill 正本 = `<bundle>/../skills`（seed.ts defaultSourceDir 上溯一级约定）。改 dist-npm 布局三处要一起动。
+- **坑（esbuild 提升）**：index.ts 顶部的 `import 'dotenv/config'` 被 esbuild 提升到 bundle 顶层 → 任何 CLI 动词都会加载 **cwd 的 .env**；其中 PORT 对 `run web` 是显式语义（占用即拒启）。在含 PORT 的仓库目录下跑 `studio run web` 不带 --port 会被 .env 的 PORT 卡住。
+- **apps/api 的 tsc dist 不能被 node 直跑**（tsconfig module ESNext 而包无 `type: module`，产物含 ESM import + 裸 require/__dirname）——npm 形态不走 tsc dist，`pnpm start`/`dev` 走 tsx；不要再给 tsc dist 加 bin 指向（apps/api bin 已于 #571 移除）。
+- CJS 遗迹：部分模块仍有 `require(...)` 惰性调用——bundle 靠 banner 的 createRequire 兜底，dev 靠 tsx；改 ESM 化时逐文件处理，别指望 tsc 产物直接跑。
+- **checkPrerequisites 测试口径（#577）**：scanAllProviders 真机全量扫描成本随 provider 探测增长（#573 注册表扫描、#574 模型探测后复审环境实测 43-55s），`__tests__/server.test.ts` 已用 importOriginal 部分 mock 隔离——该文件任何用例不得再打真扫描/留集成级超时窗口；要真扫描覆盖请放 e2e。
+- `studio up` 语义不动，但端口口径已随 #573 收口：启动前经 port-probe 解析（PORT 显式占用即拒启，缺省 3001 动态顺延上限 +100），ops preflight 的 lsof abort 与 index.ts 的 EADDRINUSE 3s 无限重试均已删除（后者归 utils/listen-error.ts，listen 竞态撞占用 = 拒启）。checkPrerequisites 的 agent CLI 检查同票对齐 provider 注册表扫描（不再硬编码 claude），缺失只警告不阻断。