dsh-plugin-t-expert 0.2.7 → 0.2.10

package/lib/teams/members.js

@@ -70,7 +70,7 @@ export function selectFallbackRoute(current, fallback, failureCode, alreadySwitc
     return { retry: true, switched: true, selection: fallback };
 }
 /** Deliver a durable member report to the live captain at its next model step. */
-export function steerCaptainReport(captain, from, content) {
+export function steerCaptainReport(captain, from, content, logger) {
     try {
         captain.steer(createUserMessage({
             content: [{ type: 'text', text: `T Team message from member ${from}:\n\n${content}` }],
@@ -78,7 +78,10 @@ export function steerCaptainReport(captain, from, content) {
         }));
         return true;
     }
-    catch {
+    catch (error) {
+        // 投递失败必须留痕：调用方只拿到一个布尔值（true=实时投递 / false=回落持久信箱），
+        // 不留日志就只能靠猜「这次为什么走了信箱」。steer 的异常根因在这里唯一可见。
+        logger?.warn?.(`[t-team] 向队长实时投递消息失败，已回落到持久信箱：${error instanceof Error ? error.message : String(error)}`);
         return false;
     }
 }
@@ -138,7 +141,7 @@ export async function failMemberOpenAttempt(ctx, stateRoot, teamId, memberName,
     // Use the same lease/acknowledgment contract as send_message, outside the
     // team lock: steering can synchronously start another agent turn.
     const captain = ctx.agents.get(brandedSessionId(prepared.captainSessionId));
-    const delivered = captain !== undefined && steerCaptainReport(captain, memberName, prepared.message.content);
+    const delivered = captain !== undefined && steerCaptainReport(captain, memberName, prepared.message.content, ctx.logger);
     await withTeamLock(lockKey, () => delivered
         ? acknowledgeMailbox(stateRoot, teamId, CAPTAIN_KEY, [prepared.message.id])
         : releaseMailboxDelivery(stateRoot, teamId, CAPTAIN_KEY, [prepared.message.id]));

package/lib/teams/quality-gates.js

@@ -97,14 +97,37 @@ export function pathMatchesScope(path, pattern) {
     const rawPattern = pattern.trim().replaceAll('\\', '/');
     if (rawPattern.startsWith('~') || rawPattern.startsWith('/') || /^[A-Za-z]:/.test(rawPattern))
         return false;
+    // 审计 N-20：旧实现只在模式**以 `/` 结尾**时才当目录，于是 `inScope: ["src"]` 对 `src/a.ts`
+    // 返回 false —— 写域等于没声明，真正该拦的写冲突会被放过。这里补齐两种常见写法：
+    //   · `src`  —— 不含扩展名的裸目录名，按目录前缀处理（含 `.` 的仍按文件精确匹配，保住 `src/a.ts` 语义）
+    //   · `src/*` / `src/**` —— 单层 / 任意层通配
     const directory = rawPattern.endsWith('/');
+    const wildcard = rawPattern.includes('*');
+    const bareDirectory = !directory && !wildcard && !rawPattern.includes('.') && rawPattern !== '.' && rawPattern !== '';
+    if (wildcard) {
+        const normalizedWildcardPattern = normalizeWorkspacePath(rawPattern);
+        if (normalizedWildcardPattern === undefined)
+            return false;
+        // 逐段翻译：`*` = 单层，`**` = 任意层；其余段按字面量并转义正则元字符。
+        const escaped = normalizedWildcardPattern
+            .split('/')
+            .map((segment) => {
+                if (segment === '**')
+                    return '.*';
+                if (segment === '*')
+                    return '[^/]+';
+                return segment.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&');
+            })
+            .join('/');
+        return new RegExp(`^${escaped}$`, 'u').test(normalizedPath);
+    }
     const normalizedPattern = normalizeWorkspacePath(rawPattern);
     if (normalizedPattern === undefined) {
         if (directory && (rawPattern === './' || rawPattern === '/' || rawPattern === '.'))
             return true;
         return false;
     }
-    if (directory || rawPattern === './' || rawPattern === '.') {
+    if (directory || bareDirectory || rawPattern === './' || rawPattern === '.') {
         if (normalizedPattern === '')
             return true;
         return normalizedPath === normalizedPattern || normalizedPath.startsWith(`${normalizedPattern}/`);

package/lib/teams/state.js

@@ -235,14 +235,26 @@ export function readTeamSync(stateRoot, teamId) {
 }
 /**
  * Persist one team record (inside the caller's lock).
+ *
+ * **落盘前必须先过读侧同一套判据（审计 N-18）**：`readTeam` 会 `coerceTeamState`，不合法就抛
+ * `invalid T Team state in team "<id>"`。曾经的缺陷是 `writeTeam` **完全不校验**，于是状态可以被写成
+ * 引擎自己拒绝读的形态（例如 provider 每次 spawn 返回同一个 childId → 成员 id 重复），
+ * 之后**任何**团队工具都会永久抛错、整支团队报废，而错误串里没有任何可定位字段。
+ * 写侧与读侧用同一判据，两者就无法再分叉：能写下去的，一定读得回来。
  * @param stateRoot - resolved absolute state root directory.
  * @param state - the record to persist.
  */
 export async function writeTeam(stateRoot, state) {
+    const teamId = isRecord(state) ? state['id'] : undefined;
+    if (coerceTeamState(JSON.parse(JSON.stringify(state)), teamId) === undefined) {
+        throw new Error(`refusing to persist invalid T Team state for team "${String(teamId ?? '(缺少 id)')}"：`
+            + '写入前校验未通过（与 readTeam 同一判据）。常见原因：成员 id 重复、成员缺 joinedAt、'
+            + 'status 不在 idle/working/removed 之内、任务缺 createdAt/updatedAt/dependencies。');
+    }
+    await mkdir(join(stateRoot, state.id), { recursive: true });
     await atomicWriteText(join(stateRoot, state.id, 'team.json'), JSON.stringify(state, null, 2));
 }
-/** Read the durable set of member session ids retired by remove/delete. */
-function parseRetiredMemberIds(raw) {
+/** Read the durable set of member session ids retired by remove/delete. */function parseRetiredMemberIds(raw) {
     const parsed = JSON.parse(stripLeadingBom(raw));
     if (!Array.isArray(parsed) || parsed.some(value => typeof value !== 'string' || value === '')) {
         throw new Error('invalid T Team retired member index');

package/lib/teams/tools.js

@@ -15,6 +15,7 @@ import { appendTeamEvent, captainSessionOf } from "./events.js";
 import { acknowledgeMailbox, appendMailbox, archiveTeamDir, beginTaskAttempt, CAPTAIN_KEY, createMessage, createTeamDir, findTeamByCaptain, findTeamByParticipant, cancelUnfinishedTask, invalidateTaskAttempt, readUnreadMailbox, recordRetiredMemberIds, releaseMailboxDelivery, readTeam, sanitizeKey, transitionError, unsatisfiedDependencies, withTeamLock, writeTeam, removeTeamDir, validateCreateTask, evaluateQualityCompletion, planQualityFollowUp, resumeTeamState, buildCoverageMatrix, canDeclareDelivery, describeQualityLoop, sanitizeReviewAcceptance, sanitizeReviewObjective, normalizeBlankOptionalTaskFields, taskKindOf, } from "./state.js";
 import { deliverToMember, installRetiredMemberGuard, installMemberSelectionRuntime, interruptMember, memberActivity, resolveMemberLlmSelection, spawnMember, steerCaptainReport, validateMemberLlmSelections, } from "./members.js";
 import { TERMINAL_TASK_STATUSES } from "./types.js";
+import { normalizeAssigneeForCreate } from "./assignee-contract.js";
 import { installTeamScheduler } from "./scheduler.js";
 import { resolveTeamProfile } from "./profiles.js";
 export { steerCaptainReport } from "./members.js";
@@ -114,45 +115,62 @@ function trimmedOptional(value) {
     const trimmed = value?.trim();
     return trimmed === undefined || trimmed === '' ? undefined : trimmed;
 }
-/** Validate references and cycles before a staged graph can be saved or run. */
-function validateStagedGraph(team, requireRunnable) {
+/** Collect every staged-graph problem: empty subject, bad assignee, unknown/self dependency, cycles. */
+function collectStagedGraphProblems(team, requireRunnable) {
+    const problems = [];
     const members = team.members.filter((member) => member.status !== 'removed');
     if (requireRunnable && members.length === 0)
-        throw new Error('add at least one member before approving the plan');
+        problems.push('add at least one member before approving the plan');
     if (requireRunnable && team.tasks.length === 0)
-        throw new Error('add at least one task before approving the plan');
+        problems.push('add at least one task before approving the plan');
     const memberNames = new Set(members.map((member) => member.name));
     const taskIds = new Set(team.tasks.map((task) => task.id));
     for (const task of team.tasks) {
-        if (task.subject.trim() === '')
-            throw new Error(`task "${task.id}" must have a subject`);
-        if (task.assignee !== undefined && task.assignee !== CAPTAIN_KEY && !memberNames.has(task.assignee)) {
-            throw new Error(`task "${task.id}" assignee "${task.assignee}" is not an active member`);
+        if (String(task.subject ?? '').trim() === '')
+            problems.push(`task "${task.id}" must have a subject`);
+        if (task.assignee !== undefined && task.assignee !== null && task.assignee !== CAPTAIN_KEY && !memberNames.has(task.assignee)) {
+            problems.push(`task "${task.id}" assignee "${task.assignee}" is not an active member`);
         }
-        for (const dependency of task.dependencies) {
+        for (const dependency of task.dependencies ?? []) {
             if (dependency === task.id)
-                throw new Error(`task "${task.id}" cannot depend on itself`);
-            if (!taskIds.has(dependency))
-                throw new Error(`task "${task.id}" depends on unknown task "${dependency}"`);
+                problems.push(`task "${task.id}" cannot depend on itself`);
+            else if (!taskIds.has(dependency))
+                problems.push(`task "${task.id}" depends on unknown task "${dependency}"`);
         }
     }
     const visiting = new Set();
     const visited = new Set();
     const byId = new Map(team.tasks.map((task) => [task.id, task]));
-    const visit = (taskId) => {
-        if (visiting.has(taskId))
-            throw new Error(`task dependency graph contains a cycle at "${taskId}"`);
+    const visit = (taskId, trail) => {
+        if (visiting.has(taskId)) {
+            problems.push(`task dependency graph contains a cycle: ${[...trail, taskId].join(' → ')}`);
+            return;
+        }
         if (visited.has(taskId))
             return;
         visiting.add(taskId);
         for (const dependency of byId.get(taskId)?.dependencies ?? [])
-            visit(dependency);
+            visit(dependency, [...trail, taskId]);
         visiting.delete(taskId);
         visited.add(taskId);
     };
     for (const task of team.tasks)
-        visit(task.id);
+        visit(task.id, []);
+    return problems;
 }
+/**
+ * Validate references and cycles before a staged graph can be saved or run.
+ *
+ * 抛**第一条**问题（调用方的门禁语义：越早拒绝越好）。需要"一次报全部"的调用方
+ * （插件侧的 `t_team_plan_check` 只读预检）用导出的 `collectStagedGraphProblems`，
+ * 不要自己复刻规则 —— 两处规则一旦漂移，预检就会说 ok 而引擎拒绝。
+ */
+function validateStagedGraph(team, requireRunnable) {
+    const problems = collectStagedGraphProblems(team, requireRunnable);
+    if (problems.length > 0)
+        throw new Error(problems[0]);
+}
+export { collectStagedGraphProblems };
 function memberOpenTask(team, memberName, exceptTaskId) {
     return team.tasks.find(task => task.id !== exceptTaskId
         && task.assignee === memberName
@@ -1034,7 +1052,7 @@ export function registerTTeamTools(ctx, config) {
     }));
     ctx.tools.register(defineTool({
         name: 't_team_create_task',
-        description: 'Create a task in your team\'s task list. Every call must include a non-empty subject, including verification and review tasks. Tasks can depend on other tasks (dependencies): a task is only claimable once every dependency is completed. Optionally assign it to a member, who still claims it before working.',
+        description: 'Create a task in your team\'s task list. Every call must include a non-empty subject, including verification and review tasks. Tasks can depend on other tasks (dependencies): a task is only claimable once every dependency is completed. Optionally assign it to a member, who still claims it before working. Omit assignee to put the task in the shared pool; the captain cannot be set here — take a task over with t_team_reassign_task(assignee="captain").',
         parameters: {
             subject: { type: 'string', required: true, description: 'Required non-empty title for this task. Never omit it, including for verification or review tasks.' },
             description: { type: 'string', description: 'What needs to be done, in detail.' },
@@ -1043,7 +1061,7 @@ export function registerTTeamTools(ctx, config) {
                 items: { type: 'string' },
                 description: 'Task ids this task depends on (must be completed before this task can be claimed).',
             },
-            assignee: { type: 'string', description: 'Optional member name this task is intended for.' },
+            assignee: { type: 'string', description: 'Optional active member name this task is intended for. Omit for the shared pool. Never "captain": create the task unassigned, then take it over with t_team_reassign_task(assignee="captain").' },
             kind: {
                 type: 'string',
                 enum: ['work', 'requirements', 'implementation', 'verification', 'review', 'repair', 'integration'],
@@ -1133,8 +1151,13 @@ export function registerTTeamTools(ctx, config) {
                         throw new Error(`dependency "${dependency}" does not exist in team "${fresh.name}"`);
                     }
                 }
-                if (args.assignee !== undefined)
+                if (args.assignee !== undefined) {
+                    // 预留键 `captain` 必须在这里被拦下并**指向 reassign_task**：
+                    // 直接丢给 requireMember 只会回一句 no active member named "captain"，
+                    // 那是按成员名精确匹配的报错，完全不提示正确入口（曾经的实际缺陷）。
+                    normalizeAssigneeForCreate(args.assignee);
                     requireMember(fresh, args.assignee);
+                }
                 const kind = gate.kind ?? 'work';
                 const objective = kind === 'review' || kind === 'requirements'
                     ? sanitizeReviewObjective(input.objective)
@@ -1681,7 +1704,7 @@ export function registerTTeamTools(ctx, config) {
             if (prepared.kind === 'captain') {
                 let delivered = 'mailbox';
                 if (captain !== undefined && prepared.identity.kind === 'member') {
-                    delivered = steerCaptainReport(captain, prepared.from, args.content) ? 'live' : 'mailbox';
+                    delivered = steerCaptainReport(captain, prepared.from, args.content, ctx.logger) ? 'live' : 'mailbox';
                 }
                 if (delivered === 'live') {
                     await withTeamLock(teamLockKey(stateRoot, prepared.fresh.id), () => (acknowledgeMailbox(stateRoot, prepared.fresh.id, CAPTAIN_KEY, [prepared.message.id])));

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "dsh-plugin-t-expert",
-  "version": "0.2.7",
+  "version": "0.2.10",
   "type": "module",
-  "description": "T Expert — a 315-expert, 22-division roster with full Chinese translations, as a standalone DeepSeek Harness plugin, with a built-in multi-agent team engine (T Team).",
+  "description": "T Expert — a 316-expert, 22-division roster with full Chinese translations, as a standalone DeepSeek Harness plugin, with a built-in multi-agent team engine (T Team).",
   "license": "MIT",
   "author": "jiuaiwo",
   "keywords": [
@@ -67,10 +67,11 @@
     }
   },
   "scripts": {
-    "build": "node ../build-client.mjs",
-    "verify": "node ../verify.mjs",
-    "sync-data": "node ../sync-data.mjs",
-    "prepublishOnly": "npm run build && npm run verify && node ../sync-data.mjs --check"
+    "typecheck": "tsc -p tsconfig.json",
+    "build": "node tools/build-client.mjs",
+    "verify": "node tools/verify.mjs",
+    "sync-data": "node tools/sync-data.mjs",
+    "prepublishOnly": "npm run typecheck && npm run build && npm run verify && node tools/sync-data.mjs --check"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
@@ -100,9 +101,6 @@
     "@deepseek-ai/dsh": {
       "optional": true
     },
-    "@deepseek-ai/dsh-agent": {
-      "optional": true
-    },
     "@deepseek-ai/dsh-api-remotes": {
       "optional": true
     },
@@ -124,33 +122,22 @@
     "@deepseek-ai/dsh-client-ui-slots": {
       "optional": true
     },
-    "@deepseek-ai/dsh-llm": {
-      "optional": true
-    },
-    "@deepseek-ai/dsh-session": {
-      "optional": true
-    },
     "@deepseek-ai/dsh-settings": {
       "optional": true
     },
-    "@deepseek-ai/dsh-subagent": {
-      "optional": true
-    },
     "@deepseek-ai/dsh-system-prompt": {
       "optional": true
     },
-    "@deepseek-ai/dsh-tools": {
-      "optional": true
-    },
-    "@deepseek-ai/dsh-typert-protocol": {
-      "optional": true
-    },
-    "@deepseek-ai/schemastery": {
-      "optional": true
-    },
     "react": {
       "optional": true
-    }
+    },
+    "@deepseek-ai/schemastery": {},
+    "@deepseek-ai/dsh-tools": {},
+    "@deepseek-ai/dsh-llm": {},
+    "@deepseek-ai/dsh-typert-protocol": {},
+    "@deepseek-ai/dsh-session": {},
+    "@deepseek-ai/dsh-subagent": {},
+    "@deepseek-ai/dsh-agent": {}
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "^4.0.2",
@@ -161,7 +148,6 @@
     "@deepseek-ai/dsh-attachment": "^0.1.5-rc.1",
     "@deepseek-ai/dsh-client-connection": "0.1.5-rc.1",
     "@deepseek-ai/dsh-client-locale": "0.1.5-rc.1",
-    "@deepseek-ai/dsh-client-runtime": "0.1.1-rc.2",
     "@deepseek-ai/dsh-client-ui-input-trigger": "0.1.5-rc.1",
     "@deepseek-ai/dsh-client-ui-primitives": "0.1.5-rc.1",
     "@deepseek-ai/dsh-client-ui-settings": "0.1.5-rc.1",
@@ -178,9 +164,11 @@
     "@deepseek-ai/dsh-util-time": "^0.1.5-rc.1",
     "@deepseek-ai/dsh-util-values": "^0.1.5-rc.1",
     "@deepseek-ai/schemastery": "^3.18.2",
+    "@types/node": "^22.20.2",
     "esbuild": "^0.25.0",
     "react": "^18.3.1",
-    "react-dom": "^18.3.1"
+    "react-dom": "^18.3.1",
+    "typescript": "^5.9.3"
   },
   "dependencies": {
     "zod": "^4.4.3"

package/skills/dsh-harness-languages/SKILL.md

@@ -0,0 +1,175 @@
+---
+name: dsh-harness-languages
+description: Use when writing, reviewing, or debugging any code in the deepseek-harness monorepo and you need that language's rules, layout, or toolchain — TypeScript on Node, the React browser client (TSX/CSS Modules), the Python SDK, the C Node-API addon, Cordis YAML composition, SQLite storage, shell, or the build/test toolchain (pnpm, tsc, tsdown, vitest, tsx, oxlint, Electron, Vite).
+---
+
+# DeepSeek Harness：语言与技术栈
+
+一份按语言/技术栈拆的落地参考。先看清「这段代码属于哪一面、哪个语言面」，再动手。
+
+## 总览
+
+| 语言 / 技术 | 位置 | 运行时与工具链 |
+|---|---|---|
+| **TypeScript（Host/Node）** | `packages/**`、`apps/cli`、`apps/desktop*`、`scripts/` | Node ^22.19 \|\| >=24、ESM、`tsc -b` + `tsdown`、`tsx` 跑源码 CLI |
+| **TypeScript/TSX（Client/浏览器）** | `packages/client/**`、`apps/web` | React 18、`react-jsx`、Vite、CSS Modules + `clsx` |
+| **Python 3.10+** | `python/sdk`、`python/sdk-runtime` | hatchling、uv、pydantic v2、pytest；stdio 上的 JSON-RPC 客户端 |
+| **C（C11）** | `native/system/packages/entry/src/*.c` | Node-API（NAPI_VERSION=8）、`cc`/`musl-gcc`、预编译平台包 |
+| **YAML（Cordis 组合）** | `packages/bundle/**/*.cordis.yml`、preset 的 `agent.cordis.yml`、profile patch | Loader + Schemastery `Config` 校验 |
+| **SQLite** | `packages/storage/storage-sqlite`、`packages/session-query/session-query-sqlite` | `node:sqlite` 的 `DatabaseSync`、FTS5 |
+| **Shell** | `packages/shell/*`、`scripts/*.sh` | bash / pwsh executor + sandbox 包装 |
+| **Markdown（文档）** | `docs/**`、包 README、`.agents/notes/**` | 文档门禁（`doc-sync`） |
+
+所有 npm 包名是 `@deepseek-ai/dsh-<name>`；`@deepseek-ai/cordis` 是每个 harness 包的 peerDependency（+ dev）。
+
+---
+
+## TypeScript（Host / Node）
+
+**编译形态**（`tsconfig.base.json`）：`target: es2024`、`module: esnext`、`moduleResolution: bundler`、`strict: true`、`exactOptionalPropertyTypes: true`。
+
+- **到处是 ESM**（`"type": "module"`）。跨包用包名 import，**包内相对导入写 `.ts` 后缀**。
+- `dsh` CLI 的源码启动走 `node --import tsx/esm`（tsx 的 ESM-only hook），所以它能触达的模块必须保持 ESM（不能有 CJS-only 导出）——Node 原生 TS 模式在 engines 范围内不可用。
+- **Host / Client 是两个聚合工程**：Host 包注册进 `tsconfig.host.json`，Client 包注册进 `tsconfig.client.json`；`tsconfig.json` 是 solution（`files: []`），`tsconfig.base.json` 是路径映射门面（**永远不要给它加 `include`/`files`**）。原因：两侧都在同一批 key 上 declaration-merge cordis 的 `Context`，一个 program 同时看到两份会报冲突 —— 该冲突只存在于 `ts.Program` 内，模块解析不会触发。
+- 需要构建整仓 `ts.Program` 的脚本要显式以 `tsconfig.host.json` 或 `tsconfig.client.json` 为种子，**绝不能用 root solution**。
+- 六个包是 Host/Client 分裂包，各带两个 leaf config + 只用 solution 的根：`api/remotes`、`api/gateway`、`api/session-controller`、`api/workspace-controller`、`client/connection`、`session-query/session-log-export`。
+
+**插件导出形态（最关键的一条）**：
+
+- **service 包 `export default` 它的 service class。**
+- **function plugin 命名导出 `name` / `inject` / `Config` / `apply`，且不能有 default export。** 混用会让 Loader 丢弃该 function plugin 的 namespace（见 [postmortem 0001](docs/postmortem/0001-acp-default-export-drops-inject.md)）。
+- 可选服务用 **`ctx.get(name)`**；`ctx.<name>` 只留给已声明 injection 的服务 —— 属性代理对拓扑敏感，`ctx.get` 读全局服务存储。
+
+**类型与写法**：
+
+- 类型化事件用 **declaration merging** 与可合并扩展的 map。`SessionEventMap` 成员默认 required-on-read；事件 JSDoc 需要 `@mode` 和 payload `@param`；payload 里没有的 scoped key 需要 `@dshScopeScan unsupported`。只有结构性格式变化才 bump `SESSION_FORMAT_VERSION`。
+- 判别式 tag 上做 switch；封闭联合以 `assertNever`（`@deepseek-ai/dsh-util-values`）收尾。
+- 跨边界的不透明 id 用 `Branded<B>` / `BrandedNumber<B>` + `brandString` / `brandNumber`（`packages/util/brand`，包名 `@deepseek-ai/dsh-brand`），不用裸 `string`。
+- **每个 module 与 export 都要有简洁 JSDoc**，函数式导出要有 `@param`/`@returns` —— `verify-export-jsdoc` 强制。公有 service 方法要记参数与非 void 返回。
+- 剩下的 `any` 要解释为什么无法收窄。
+- `src/types.ts` 只放类型，不放运行时代码；测试放包级 `tests/`，不放 `src/__tests__/`。
+- 空 `catch` 命名它吞掉什么、为什么别的到不了；`try` 只包一条语句。
+- 注释写局部契约（行为、失败、时序、所有权、模态、例外、后果），**不写推理过程、不复述代码、不写测试走查**。
+
+**远程过程调用（Typert）**：业务 service 在 Host 用 `@Remote` / `@RemoteScope` 声明可调用方法；Host 构建生成 Host-for-Client 类型与运行时贡献，Client 的 `api-remotes` 在 `ctx.remote` / `agentCtx.remote` 下加载它们。手工写的 `remote` 类型会漂移。
+
+**边界校验**：只在 parser/config、queued、模型/工具 JSON、durable/file、worker、process、wire 边界做运行时校验。同一进程内的静态类型边界信任 TypeScript，不加多余校验。
+
+---
+
+## TypeScript / React（浏览器客户端）
+
+位置：`packages/client/**`（`ui-*` 插件 + `web` 引导内核 + `store`/`connection`/`slots`/`locale`/`modules`/`resources`），应用层在 `apps/web`。
+
+- React **18**，`jsx: react-jsx`，浏览器 lib（`ES2024 + DOM + DOM.Iterable`），`types: []` 起步（需要 Node 类型的包局部覆写）。继承 `tsconfig.base.client.json`。
+- **样式**：CSS Modules（`*.module.css`，约 130 个）+ `clsx`。**不要引入组件库，不要用 Tailwind。**
+- **token 归 `ui-theme` 所有**：静态色阶、语义别名、排版、动效、渐变、阴影、滚动条、明暗偏好都在 `packages/client/ui-theme/src/styles/`，对外暴露 `--dsw-*`。特性包只用 `--dsw-alias-*` 语义别名，**不写死调色板值或字面颜色**，也不在特性组件 CSS 里写主题选择器。
+- 全局样式表放 `ui-theme/src/styles/`；组件样式放组件旁边。组件可定义局部自定义属性，但共享的颜色/排版/高度/动效归 theme 包。
+- **先复用再改样式**：[ui-primitives 组件目录](packages/client/ui-primitives/README.md#component-catalog)是唯一跨特性包的通道；刻意的视觉差异做成它的 prop，而不是再复制一份。
+- 抬高面（菜单、popover、modal、面板、浮动按钮、composer）设 `border: 0` 并用 `var(--dsw-elevation-*)`；**不要把 `--dsw-alias-border-*` 边框和 elevation 阴影配在一起**（ui-theme 的 spec 会拒绝）。
+- 中立实色边框与分隔线画 `0.5px`（Chromium 上正好一个设备像素）；虚线语义与状态色边框保持 1px。
+- 圆角继承 ui-theme 的 superellipse smoothing；每个整圆 `border-radius`（`50%`、`100%`、胶囊）都要配 `corner-shape: round`。
+- 可点击的产物链接统一用 `--dsw-alias-link` + `font-weight: 500`，静止无下划线，hover/focus 为 3px 偏移点状下划线。
+- 保留键盘焦点可见性与 reduced-motion 行为。
+- **产品文案归 locale 所有**：走类型化字典 + `t` 座位或本地化 primitive props。JSX、模板、helper 返回值、可访问性属性、primitive 默认值里的硬编码产品文案会被 `verify-client-ui-i18n` 拒绝；用户/模型/wire 数据与代码 token 原样保留。
+
+---
+
+## Python 3.10+
+
+位置：`python/sdk`（`deepseek_harness`，PyPI `deepseek-harness-sdk`）与 `python/sdk-runtime`（`deepseek_harness_runtime`，PyPI `deepseek-harness-runtime-bin`）。
+
+- `requires-python = ">=3.10"`；`pydantic>=2.12,<3`；构建后端 hatchling（`hatchling==1.30.1`）；依赖组测试用 pytest ≥8，`pytest.ini` 在仓库根。
+- 包布局是 `src/` 布局：`python/sdk/src/deepseek_harness/{__init__,api,client,errors,models}.py`。
+- **角色**：通过 stdio 上的换行分隔 JSON-RPC 驱动 dsh 子进程。`HarnessClient` 是同步客户端；`HarnessConfig` 持有 `dsh_bin`、`profile`（默认 `sdk`）、`patches`、`dsh_home`、`cwd`、`env`、各类超时。
+- **每次启动都必须显式指定 Harness home；Python 绝不静默读 `~/.dsh`。**
+- Python 侧暴露的是 profile 选择 + 有序 patch 文件，不是完整 Cordis 树；持久外部插件通过 `dsh plugin` 安装。
+- 上游 `errors.py` 里的 `JsonRpcError` / `TransportClosedError` 是传输层的失败类型；模型结构在 `models.py`（`IncomingRequest`、`InitializeResponse`、`JsonObject`、`JsonValue`、`Notification`）。
+- `sdk-runtime` 把正常 `dsh` CLI 打包成 `deepseek-harness-sdk-runtime-<platform>-<arch>`；`hatch_build.py` 注入运行时可执行文件，editable 安装走 `[tool.uv.sources]`。跨平台 CI 由 master-only 的 Python-runtime 工作流负责。
+- agent-loop / session 生命周期 / `SessionEventMap` 改动必须同步更新 **Python SDK 的单可执行快照**（`scripts/snapshots/python-sdk-single-exe/`）。
+
+---
+
+## C（Node-API 原生插件）
+
+位置：`native/system`（workspace 包 `@deepseek-ai/node-addon-system`，平台包 `darwin-arm64`、`darwin-x64`、`linux-arm64`、`linux-x64` + `entry`）。
+
+- 两个能力：**Linux Landlock launcher**（`landlock-run`：`launcherPath`、`probe`、`grantArgs`）与 **POSIX flock**（`tryLockExclusive(fd): Promise<void>`）。
+- 编译：`-std=c11 -Wall -Wextra -Werror`；Node-API 走 `-DNAPI_VERSION=8 -fPIC -fvisibility=hidden`；musl 用 `musl-gcc -static`。
+- 源码是 `packages/entry/src/main.c` 与 `flock.c`，通过 `lib/` 的 TS 门面导出（`tc -b` 之后 `prepack` 跑 `verify-entry-lib.mjs`）。
+- **消费者安装从不编译原生代码**：平台二进制放在平台包里，由 entry 包以 npm optionalDependencies 承载。
+- 语义契约在 `native/system/docs/`（`architecture.md`、`cli-contract.md`、`flock-contract.md`、`naming.md`、`packaging.md`、`release.md`、`support-matrix.md`）—— 改行为同步改契约文档。
+- 重要语义：import 任一 entry **不会**加载 addon；Landlock 可执行文件缺失时 `probe` 报不可用，flock binding 缺失时获取锁直接 reject。两者都不会静默降级或自行编译。
+- flock 语义：非阻塞独占 flock；竞争以 `EAGAIN`/`EWOULDBLOCK` reject；打开文件的最后一个描述符关闭时释放锁；描述符要保持到完成。
+
+---
+
+## YAML：Cordis 组合与配置
+
+- `cordis.yml` 里 **`!!js` 只允许出现在 plugin 的 `config` 和 entry 的 `disabled` 下**（注意是双感叹号，不是 `!js`）；其他元数据保持字面量。条件组合用 patch overlay 表达。
+- 每个 row 的 `config` 由该插件导出的 Schemastery `Config` 校验；**配置字段都有 JSDoc**，生成的 `docs/config-catalog.md` 是穷尽权威。
+- patch **按 `id` 定位 row**：替换整条 config，或插入新行。
+- 裸插件（bare plugin）必须出现在其 resolver manifest 的 `dependencies` 里，`verify-cordis-config` 强制。
+- agent preset 的 `agent.cordis.yml` 是 **agent 平面**：只放该 session 往注册表里贡献的东西；发布服务必须在带 `isolate` 的 group 内。`baseUrl` 在该文件中可用（preset 自身目录），`{{model}}`/`{{cwd}}` 是 persona 模板变量。
+- preset 显示元数据在旁边的 `preset.yml`，只允许 `name` / `description` / `order`（`id` 是目录名，`trust` 来自发现根，二者不可在此声明）。
+- 读失败一律降级为「无元数据」：**显示文本坏了不该让 preset 起不来**。
+
+---
+
+## SQLite
+
+- 用 **`node:sqlite` 的 `DatabaseSync`**（内建，无第三方驱动），不是 better-sqlite3。
+- 两个后端：`packages/storage/storage-sqlite`（kv facet，`STORAGE_SQLITE_SCHEMA_VERSION = 1`）与 `packages/session-query/session-query-sqlite`（`SESSION_QUERY_SQLITE_SCHEMA_VERSION = 8`，FTS5 全文检索）。
+- 版本存在 **`PRAGMA user_version`**：单调递增；`0` 视为未盖章并写入当前版本；**不匹配就报错拒绝打开**，不静默迁移、不降级。
+- 会话数据本身是 append-only JSONL 日志（`session.jsonl[.zstd]`、v1+ 为 `session.vN.jsonl[.zstd]`）。已提交的 generation 路径**永不重命名、覆盖或删除**；SQLite 只服务查询与 kv 面。
+
+---
+
+## Shell
+
+- 两个 executor provider：`dsh-bash-local` / `dsh-bash-sandbox`（Windows 上是 pwsh 对应实现），模型可见工具是 `dsh-tool-bash` / `dsh-tool-pwsh`。
+- `ctx.shell` 的 request/spec 分离是「包边界显式优于隐式」的模板：默认值解析是拥有方显式的一步 `resolve(request): Spec`，不是 `run()` 里藏的 `?? default`。
+- 子进程要经 sandbox backend 包装 argv。**不要把宿主的运行环境交给不受信输出**：spawn 的命令使用擦洗过的 env（丢弃 `*KEY*`/`*SECRET*`/`*TOKEN*`/`*PASSWORD*`），临时/溢出文件用私有 0700 目录、随机文件名、独占 owner-only 打开（`'wx'`、`0o600`）。
+- 可能是符号链接或 Windows junction 的路径，先 `lstatSync().isSymbolicLink()` 再 `unlinkSync`；递归 `rmSync` 只留给确认的真实目录。
+- 仓库脚本：`scripts/*.ts` 是主入口；只有 7 个 `.sh`（CI/打包辅助）。脚本里的诊断与门禁多数挂在 `scripts/run-gates.ts`。
+
+---
+
+## Markdown 与文档
+
+见 [dsh-harness-project](SKILL.md) 的技能文档分层一节：一段一个物理行、只写当前状态、生成的参考文档不手改、跨引用用相对路径。
+
+---
+
+## 构建与验证工具链
+
+| 工具 | 角色 |
+|---|---|
+| **pnpm 11.7.0**（corepack） | workspace + lockfile；workspace 目录：`vendor/*`、`packages/*/*`、`native/system`、`native/system/packages/*`、`apps/*`、`website` |
+| **tsc 6**（project references） | `tsc -b tsconfig.host.json` → `lib/types`；Client 同理 |
+| **tsdown** | 打包 runtime；`--env.DSH_BUILD_FACE host\|client` 选择阶段；只消费前一步 tsc 的产物，**不扫描已有构建产物来发现包** |
+| **tsx** | 跑 TypeScript 脚本与源码 CLI（`node --import tsx/esm`） |
+| **vitest 4** | 全部测试层；所有 vitest config 都通过 vite-tsconfig-paths 指向 `tsconfig.base.json`，**workspace import 永远解析到 `src`**，不走包 `exports` 到已构建的 `lib/`（那里会加载第二份 module singleton） |
+| **oxlint** | lint（`.oxlintrc.json`）；`lint:fix` 用 staged 配置 |
+| **jscpd** | `duplication` 跨文件 TS 克隆检测 |
+| **publint + NodeNext 消费者检查** | `hygiene` 门禁组 |
+| **Vite** | `apps/web` 构建前端产物；`pnpm run dev:web` 需要先有一次完整构建 |
+| **Electron 44** | `apps/desktop` 桌面应用；带私有的 Desktop Host 在打包的 Node 进程里加载后端与客户端图，走版本化分帧字节管道，**不开 Web server 或 loopback 端口** |
+| **Playwright/Chromium（测试内）** | `test:web` 浏览器快照 |
+| **hatchling / uv / pytest** | Python 侧 |
+| **cc / musl-gcc** | 原生侧 |
+
+**源码面 vs 产物面**：静态门禁与测试通过 tsconfig `paths` 解析到 `src`，必须在干净树上通过；消费已构建 `lib/` 的门禁（built smoke、`lib` 模式子进程）要显式声明该依赖。子进程启动模式由共享 dual-mode launcher 决定，**不要手写 `--import tsx`**。
+
+**构建产物污染提醒**：`pnpm run typecheck` 会先跑完整的 Host lib 阶段再跑 Client tsc；`build` 会继续 Client tsdown 与 Web build。构建把版本、7 位源码 commit、脏标记嵌进去——改完代码别指望旧的 `lib/` 还有效。
+
+---
+
+## 各语言共同的硬约束
+
+1. **一个异步操作对应一个生命周期控制器或事务**；把 readiness/cancellation/disposal/reservation/sentinel 拆成多份状态就必须各有独立 owner 或结算点。
+2. **在提交点发布状态**：通知与派生状态都在操作成功之后；缓存、prompt、UI 回声、replay、查询视图都从同一个权威源派生。
+3. **边界施加在完整结果上**：字节/token/条目/时间上限要在完整产出（含包装与元数据）已知处施加，并测试极小值、精确值、超大单块、多字节边界。
+4. **dispose 要到达静默**：teardown 必须 await 子项退出（kill → await `done`），并在 kill 之前关闭监听/通知注册表。
+5. **回调异常要在 dispatcher 内被兜住**：一个坏监听器不能 reject 它所在的 promise，也不能饿死后面的监听器。
+6. **正交结果独立上报**：超时 + exit 0 可以同时为真；`timedOut`/`signal`/`exitCode` 各报各的，不要把一个塞进另一个分支。