dsh-plugin-guide 0.1.0

package/references/official-docs/AGENTS.md

@@ -0,0 +1,149 @@
+# AGENTS.md
+
+DeepSeek Harness is a plugin-based agent harness on vendored Cordis: **everything is a plugin**. Read [docs/architecture.md](docs/architecture.md) before changing `packages/`; follow [docs/AGENTS.md](docs/AGENTS.md) for documentation.
+
+## Pre-release stance: foundation over blast radius
+
+**Remove this section at the first tagged release.** With no external consumers, prefer the correct foundation over compatibility shims: rename or repackage freely and update every reference together. Backends reject old on-disk formats. SQLite uses monotonic `SCHEMA_VERSION`; `dsh-session` keeps `SESSION_FORMAT_VERSION` at `0` with no compatibility promise.
+
+## Repository layout
+
+```
+vendor/      Vendored Cordis source — manifest + sync procedure in vendor/README.md
+packages/    @deepseek-ai/dsh-<pkg> workspaces at packages/<group>/<pkg>/
+  core/        product API spine: session, system-prompt, tools, agent, agent-loop
+  api/         Remote BFF assembly and Typert RPC gateway
+  typert/      type graph generator, loader, and runtime registry
+  llm/         LLM capability: Service Definition/Consumer + DeepSeek providers
+  e2b/         E2B POC: sandbox + FS/subprocess adapters
+  shell/        bash capability: Service Definition + local/pwsh providers + shell Consumers
+  subprocess/  subprocess capability + local process-tree provider
+  terminal/         persistent sessions
+  fs/          filesystem capability + policy
+  lsp/         language-server capability
+  skill/       skill provider registry + local impl + catalog/loader tool
+  web/         web capability: Service Definition + search/fetch providers + tool Consumer
+  compaction/     compaction capability + basic provider
+  context/     request-context plugins
+  subagent/    subagent capability: Service Definition + providers + delegation Consumers
+  bundle/      installable dsh --profile patch-layer bundles
+  workflow/    workflow capability + worker-thread provider + tool Consumer
+  todo/        todo_write tool
+  plan/        plan mode as logged state
+  preset/      per-session agent composition from preset cordis.yml files
+  guard/       loop-hygiene + tool-timeout plugins
+  self-modification/  the agent inspects/mounts its own plugins
+  hooks/       Claude Code/Codex hook bridges + wire-protocol library
+  session/     durable session data: persistence, projection, titles, telemetry
+  identity/    anonymous identity
+  settings/    user-settings capability + file provider
+  credentials/ credential-reference capability + env/.env provider
+  acp/         automation-only Agent Client Protocol server
+  interaction/ approval/interaction capabilities, permission, commands, ask-user
+  boot/        shared app-bin glue
+  sdk/         JSON-RPC protocol, server, and TypeScript client
+  examples/    demo bundles (agent-spine + CLI/ACP/JSON-RPC bins)
+  support/     dev/test infrastructure
+  util/        zero-dependency utilities
+python/      Python SDK and bundled runtime (see python/README.md)
+native/      @deepseek-ai/node-addon-landlock-run source of record (see native/README.md)
+examples/    Runnable cordis.yml leaves over packages/examples bundles (see examples/AGENTS.md)
+.agents/     Agent workflows and Agent Notes (`notes/`)
+docs/        architecture, generated catalogs, postmortems, cookbook (see docs/AGENTS.md)
+scripts/     repo gates and generators
+website/     VitePress projection of selected bilingual docs/ sources
+```
+
+Package groups: [packages/README.md](packages/README.md).
+
+## Commands
+
+```sh
+pnpm install            # pnpm workspaces, node ^22.19 || >=24
+pnpm run clean           # remove build outputs and safe residue from deleted packages
+pnpm run test           # vitest unit tests
+pnpm run test:coverage  # CI coverage gate: per-file 100% on packages/*/*/src
+pnpm run test:e2e       # real-API tests; self-skip without DEEPSEEK_API_KEY
+pnpm run test:snapshot  # keyless ACP/headless replay vs expected outputs; filter: -t <name>
+pnpm run test:snapshot:record  # re-record expected outputs (needs key)
+pnpm run typecheck
+pnpm run lint
+pnpm run duplication    # cross-file TypeScript clone detection
+pnpm run build          # tsc emits lib/types, tsdown bundles runtime
+pnpm run hygiene        # knip + publint + workspace constraints + NodeNext consumer check
+pnpm run check:windows-wine  # ONLY when diagnosing a known Windows failure (needs wine); CI owns this signal
+pnpm run doc-sync       # all documentation gates; leaf list in scripts/run-gates.ts
+pnpm run website:build  # VitePress build (doubles as dead-link check)
+pnpm dsh --profile headless "task"  # run one task from source (needs DEEPSEEK_API_KEY)
+pnpm run demo:cordis    # the agent modifies its own runtime (needs key)
+pnpm run demo:acp       # ACP automation server (needs DEEPSEEK_API_KEY)
+```
+
+### Host sandbox failures
+
+When required `gh`, `pnpm`, build, test, or generator commands fail because the agent sandbox blocks credentials, network, IPC, file watching, or nested `sandbox-exec`, retry unchanged with the narrowest host escalation before diagnosing authentication or project failure. Require sandbox evidence; never bypass genuine test failures or the product sandbox under test.
+
+### Run relevant checks locally
+
+Run checks before pushes via [dsh-pre-push-checks](.agents/skills/dsh-pre-push-checks/SKILL.md); report only commands run. After `gh stack sync`, validate immediately; do not merge before checks pass.
+
+- Match evidence to the surface: focused tests for behavior, snapshots for model or user output, `doc-sync` for docs, build/hygiene and built smokes for published paths, and real-API e2e for provider behavior.
+- Never default to the full suite or repeat a passing check for commit or push. CI owns exhaustive coverage and the platform matrix; rehearse all locally only by explicit request, for CI diagnosis, or for an irreducibly repository-wide change.
+- `test:coverage`, not `test`, is the CI coverage gate ([why](docs/testing.md)).
+
+## Secrets / .env
+
+Real-API tests and demos read `DEEPSEEK_API_KEY`, optional `DEEPSEEK_BASE_URL`, and root `.env`. cordis.yml allows `!!js` (never `!js`) under plugin `config` and entry `disabled`; other metadata stays literal, so conditional composition also uses overlays ([primer](docs/cordis-primer.md#loader-configuration)). Never commit credentials. CI e2e skips without a key; [testing.md](docs/testing.md) owns key policy.
+
+## Conventions
+
+- Every npm package is `@deepseek-ai/dsh-<name>`; vendored packages are rescoped ([mapping](docs/rescope.md)) and `private: true`. `@deepseek-ai/cordis` is a peerDependency (+ dev) of every harness package.
+- ESM everywhere (`"type": "module"`). Use package names across packages and `.ts` in local relative imports. Config subprocesses run built `lib/` under plain Node; source regressions use their declared launcher ([testing policy](docs/testing.md#test-subprocess-launch-modes)). The `dsh` CLI source launch runs through tsx's ESM-only hook (`node --import tsx/esm`); modules it reaches must stay ESM (no CJS-only exports) — Node's native TypeScript modes are unavailable across the engines range ([source-launch contract](.agents/notes/implemented/architecture/2026-07-29-dsh-source-launch-tsx-esm.md)). Raw/Web `cordis.yml` bare plugins must appear in their resolver manifest's `dependencies`; `verify-cordis-config` enforces it.
+- **Registrations are effects**: every contribution goes through `ctx.effect()` / `ctx.on()`; a registry's `register()` returns the disposer.
+- **Runtime invariants assert owned relationships.** Check authoritative event streams or mutable data, not service or method presence, plugin metadata or effects, or fixed pure examples. Without a plausible relationship, an explained empty companion is correct ([package invariant rules](packages/AGENTS.md)).
+- **Typed events use declaration merging** and merge-extensible maps. Event JSDoc needs `@mode` and payload `@param`; scoped keys absent from payloads need `@dshScopeScan unsupported`. Public service methods document parameters and non-void returns. A `SessionEventMap` member is required-on-read by default — builds that do not know its type refuse the log unless the event carries the envelope's `ignorable: true`; only structural format changes bump `SESSION_FORMAT_VERSION` ([mechanism](.agents/notes/implemented/architecture/2026-08-10-session-log-version-mechanism.md)).
+- **Switch on discriminant tags.** Closed unions end in `assertNever`; merge-extensible unions fall through a documented default.
+- **Waterfall listeners MUST call `next()`** to delegate; returning without it short-circuits the chain ([semantics](docs/cordis-primer.md#cordis-waterfall-semantics)).
+- **Model-visible ⟺ logged**: anything that reaches a model request must be reconstructable from the session log; a new model-visible input requires a session event.
+- **Plugins, not loop changes**: new behavior goes on documented extension points; changing `agent-loop` requires updating docs/architecture.md.
+- **A capability seam comprises Service Definition / Service Provider / Consumer roles.** It is complete, never one role; split only when roles evolve independently ([glossary](docs/glossary.md#capability-seam)).
+- **Prefer maintained dependencies over hand-rolling** when they genuinely delete owned code and tests ([policy](.agents/notes/implemented/process/2026-07-26-dependencies-over-hand-rolling.md)).
+- **Explicit > implicit at package boundaries**: defaulting is an explicit `resolve(request): Spec` step in the owning implementation, never a hidden `?? default` inside `run()` (the `dsh-shell` request/spec split is the template).
+- **No hardcoded tunables in plugins**: deployment-varying choices are validated `Config` fields changeable from cordis.yml; a `DEFAULT_*` constant or test hook is not configurability. Protocol constants, external specs, and security invariants stay fixed.
+- **Misconfiguration fails loud** at load when self-contained, otherwise at the earliest resolvable point; never silently skip a missing referent.
+- **Opaque cross-boundary ids are branded** (`Branded<B>` from `dsh-brand`), never bare `string`.
+- **Trust TypeScript at typed same-process boundaries.** Do not add runtime validation, fallback behavior, or hostile-input tests solely for values the static interface requires; validate at parser/config, queued, model/tool JSON, durable/file, worker, process, and wire boundaries.
+- **Source plane vs artifact plane, never mixed.** Static gates and tests resolve workspace imports through tsconfig `paths` to `src` and pass on a clean tree; gates consuming built `lib/` declare that dependency ([layout](docs/development.md#typescript-project-layout)).
+- **Keep compiler faces explicit.** Each package uses one aggregate except `api/remotes`; repo-wide programs seed a face config, never the root solution ([layout](docs/development.md#typescript-project-layout)).
+- **An empty `catch` names what it swallows** and why nothing else can reach it; keep the `try` to one statement.
+- Do not comment on facts obvious from code.
+- **Prefer symmetry for parallel values**; unexplained asymmetry usually signals a missed extraction.
+- **Tests describe behavior, not correctness.** Change obsolete behavior with its tests; explain why in the PR.
+- **Non-trivial changes MUST include an Agent Note in the same PR;** only mechanical/local edits are exempt ([scope](.agents/notes/README.md#when-to-write-one)). Archived notes are frozen: never edit or treat them as current authority ([archive policy](.agents/notes/README.md#archiving-and-deletion)).
+- **Testing policy** — [docs/testing.md](docs/testing.md). Every non-trivial model- or product-user-visible behavior change adds or updates a keyless snapshot through a real runnable example in the same PR; package tests, e2e-only assertions, and mock-only fixtures do not substitute for the assembled application transcript. Fixtures must replay on macOS/Linux; fix fixtures, not normalizers.
+- **A tool's UI render intent is part of its design**, decided up front (`generic`/`terminal`/`diff`, `locations`); presentation methods are pure functions of `args` ([cookbook](docs/cookbook/adding-a-tool.md)).
+- **Plan unit, e2e, and snapshot coverage** for capability seams, lifecycle paths, and transcript output; include missing snapshot-harness support in the same change.
+- **Choose PR history deliberately.** Split independent changes; fix the introducing PR before propagation. Standalone PRs and official stacks may merge-forward or rebase after review. Rewrites use `--force-with-lease`, abort on remote movement, never raw `--force`; an in-progress merge-forward preserves its checkpoint before taking a newer base ([rationale](.agents/notes/implemented/process/2026-08-02-native-github-stacks-and-optional-rebases.md)).
+- **Labels:** one PR `kind/*`, all material `area/*`, and native Issue Type ([taxonomy](.agents/notes/implemented/process/2026-08-08-unified-github-label-taxonomy.md)).
+- TODO markers: `FIXME`/`TODO`/`XXX` by urgency ([semantics](docs/development.md)).
+- Files end with exactly one trailing newline; `git diff --cached --check` (pre-commit) gates it.
+
+## Defensive patterns
+
+Read [docs/defensive-patterns.md](docs/defensive-patterns.md) before lifecycle, concurrency, subprocess, or teardown work.
+
+## Type safety and documentation
+
+Everything compiles under `strict: true` with `noImplicitAny`; every remaining `any` explains why narrowing is infeasible. Every module and export has concise JSDoc for its non-obvious contract; function-like exports include `@param`/`@returns`, as enforced by `verify-export-jsdoc`. Heritage-declared members, plugin-protocol slots, and constructors keep their docs at the declaring Service Definition, protocol, or class.
+
+Comments and docs state complete contracts and context, not reasoning transcripts. Use direct, concrete terms. Do not use metaphors. Before writing `contract`, `boundary`, or `shape`, ask whether a more exact term names the subject: write `response fields`, `JSON validation`, or `ESM exports` instead of `response shape`, `validation boundary`, or `module shape`. Keep `contract` for preconditions, postconditions, invariants, compatibility promises, and other obligations that callers, callees, implementers, providers, producers, or consumers rely on. Keep a literal process, wire, security, transaction, or lifecycle boundary. Do not narrate control flow or tests, preserve review history, or restate code. Keep behavior, failure, timing, ownership, and safe-use facts; link the rationale. Use [dsh-prose-standard](.agents/skills/dsh-prose-standard/SKILL.md) for decisions. Wire mechanically checkable invariants into an executed top-level gate and prove each changed acceptance path rejects an invalid case. Use narrow, justified exceptions instead of disabling a rule globally.
+
+Docs accompany every code change: update affected README and JSDoc contracts together. Routine bilingual work follows [docs/AGENTS.md](docs/AGENTS.md); only explicit user invocation may run `dsh-translate-docs`. Current-state prose, one physical line per paragraph, one home per fact, and word budgets live there.
+
+## Editing these instructions
+
+`CLAUDE.md` symlinks `AGENTS.md` at root, `packages/`, and `examples/`; edit the real file. Keep each rule self-contained while linking high-level docs. Condense when clarity survives; raise a `verify-doc-budgets` ceiling when the required content genuinely needs more space.
+
+## Vendoring policy
+
+`vendor/` packages are pinned source copies (manifest with upstream SHAs in [vendor/README.md](vendor/README.md)). Update via the sync procedure there; re-apply or retire the logged local modifications; rerun `pnpm run test && pnpm run build`.

package/references/official-docs/BENCHMARK.md

@@ -0,0 +1,3 @@
+# Running benchmarks
+
+Follow [Get started with the Python SDK](docs/user/guide/python-sdk.md) to install the SDK and run the `jsonrpc-agent` minimal variant. Use separate workspaces and session IDs for independent benchmark tasks.

package/references/official-docs/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

package/references/official-docs/CONTRIBUTING.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write CONTRIBUTING.md
+CONTRIBUTING.md: 9f30e23a6d9567db7d6097cb82e481b16dda299e
+CONTRIBUTING.zh.md: 35eb0b87fc4d9af11bef616039570dc5e6a1b309

package/references/official-docs/CONTRIBUTING.md

@@ -0,0 +1,23 @@
+# Contributing
+
+English | [中文](CONTRIBUTING.zh.md)
+
+Thank you for your interest in contributing to DeepSeek Harness!
+
+We deeply believe in the power of open source communities, and that belief has shaped this project from the very beginning.
+
+DeepSeek Harness is still at an early stage and under active development. We are sorry that we cannot accept external pull requests at the moment. However, contributing code to this repository is far from the only way to help. There are many other ways to get involved:
+
+- Identify and report issues or bugs in GitHub Discussions:
+  - Upvote discussions that you would like to bring to the team's attention. We are a very small team and may not be able to reply to every post, but we monitor them and consider them when allocating resources.
+- Contribute to the ecosystem:
+  - Create a plugin that excites you and share it with others:
+    - Associate your GitHub project with the `dsh-plugin` topic to help others discover your plugin.
+  - Write blog posts and how-to guides about DeepSeek Harness.
+  - Answer questions and help other members of the community.
+
+DeepSeek Harness is designed to be deeply customizable. We do not believe that packages in the official repository are inherently more important than packages created by the community. You may consider this repository an idea, an official showcase, and a source of inspiration, but not a mandate from us.
+
+We have already seen exciting projects emerge from the community, and we hope to see the ecosystem continue to grow in its own directions.
+
+Into the unknown.

package/references/official-docs/CONTRIBUTING.zh.md

@@ -0,0 +1,23 @@
+# 贡献
+
+[English](CONTRIBUTING.md) | 中文
+
+感谢你愿意为 DeepSeek Harness 作出贡献！
+
+我们深信开源社区的力量，这份信念从项目最初就塑造着 DeepSeek Harness。
+
+DeepSeek Harness 仍处于早期阶段，并在积极开发中。很抱歉，我们目前无法接受外部 PR（Pull Request）。不过，贡献代码远非帮助本仓库建设的唯一途径。你还可以通过许多其他方式参与进来：
+
+- 在 GitHub Discussions 中发现并报告问题或 bug：
+  - 为你希望引起团队关注的讨论投票。我们的团队规模很小，可能无法回复每个帖子，但我们会持续关注，并在分配资源时将这些讨论纳入考虑。
+- 为生态系统作出贡献：
+  - 创建令你感兴趣的插件，并分享给其他人：
+    - 为你的 GitHub 项目添加 `dsh-plugin` 话题，让其他人更容易找到你的插件。
+  - 撰写有关 DeepSeek Harness 的博客文章和操作指南。
+  - 回答问题并帮助其他社区成员。
+
+DeepSeek Harness 的设计支持深度定制。我们并不认为官方仓库中的包天然就比社区开发的包更重要。你可以将本仓库看作一种理念、一份官方示例以及一处灵感来源，而不是我们要求社区遵循的方向。
+
+我们已经看到社区中涌现出令人期待的项目，也希望生态系统继续沿着自己的方向发展。
+
+探索未至之境。

package/references/official-docs/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/references/official-docs/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write README.md
+README.md: 8a4bd01332a23ce4144c661784bc549e0ba72d21
+README.zh.md: b7bc214bfb1fd8a76a47de3f0aa242122aeb7603

package/references/official-docs/README.md

@@ -0,0 +1,35 @@
+# official-docs（官方文档逐字副本）
+
+> 本目录是 [deepseek-ai/deepseek-harness](https://github.com/deepseek-ai/deepseek-harness) 官方文档的**逐字副本**：不要在这里编辑，上游有问题反馈给上游仓库。
+> 本 README 是 dsh-plugin-guide 自有的说明文件，不是上游内容。
+
+| 内容 | 位置 | 来源（仓库内路径） |
+|---|---|---|
+| 官方 `docs/` 全文（215 篇 md，含全部 `.zh.md` 双语对） | [`docs/`](docs/) | `docs/` |
+| 仓库根开发红线 | [`AGENTS.md`](AGENTS.md) | `AGENTS.md` |
+| CLAUDE 入口（上游为 symlink，此处为其目标文本） | [`CLAUDE.md`](CLAUDE.md) | `CLAUDE.md` → `AGENTS.md` |
+| 基准测试说明 | [`BENCHMARK.md`](BENCHMARK.md) | `BENCHMARK.md` |
+| 贡献指引（中英 + i18n 元数据） | [`CONTRIBUTING.md`](CONTRIBUTING.md) · [`CONTRIBUTING.zh.md`](CONTRIBUTING.zh.md) · [`CONTRIBUTING.i18n.yaml`](CONTRIBUTING.i18n.yaml) | `CONTRIBUTING.*` |
+| 上游中文 README 与 i18n 元数据 | [`README.zh.md`](README.zh.md) · [`README.i18n.yaml`](README.i18n.yaml) | `README.zh.md` · `README.i18n.yaml` |
+| 三方声明 | [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md) | `THIRD_PARTY_NOTICES.md` |
+| 许可证 | [`LICENSE`](LICENSE) | `LICENSE` |
+| packages 组红线 | [`packages/AGENTS.md`](packages/AGENTS.md) | `packages/AGENTS.md` |
+| examples 红线 | [`examples/AGENTS.md`](examples/AGENTS.md) | `examples/AGENTS.md` |
+| 包分组总览 | [`packages/README.md`](packages/README.md) | `packages/README.md` |
+| Cordis vendoring 清单与同步流程 | [`vendor/README.md`](vendor/README.md) | `vendor/README.md` |
+| 文档站投影清单 | [`website-docs.ts`](website-docs.ts) | `website/docs.ts` |
+| 副本快照（源 ref/提交/时间，README 新鲜度印章的权威） | [`SNAPSHOT.md`](SNAPSHOT.md) | 由 `scripts/sync-official-docs.ps1` 生成 |
+
+> 上游英文 `README.md` 不进入本目录（与本 KB 索引同名冲突）；其线上快照在 `downloads/github/harness/README.md`。
+
+## 同步与校验
+
+```sh
+# 同步（源固定为 checkout 的 origin/master，未跟踪/未推送内容不会进来）
+pwsh -File scripts/sync-official-docs.ps1 [-Checkout <deepseek-harness-checkout>]
+
+# 漂移校验（KB 与 checkout 的 git 已跟踪文件逐一哈希对比）
+pwsh -File scripts/verify-kit.ps1 -Checkout <checkout>
+```
+
+同步范围只包含 git 已跟踪文件；checkout 里的本地草稿（未跟踪）与未推送提交的改动不会进入本目录。同步后 README 里的"最后核验"日期与提交号请引用 `SNAPSHOT.md`。

package/references/official-docs/README.zh.md

@@ -0,0 +1,74 @@
+# DeepSeek Harness
+
+[English](README.md) | 中文
+
+DeepSeek Harness（`dsh`）是由 [DeepSeek AI](https://deepseek.com) 开发的开源 agent harness（智能体框架）。
+
+它采用**一切皆插件**的架构，并由 [Cordis](https://github.com/cordiverse/cordis) 驱动，其设计参见论文 [_A Programming Paradigm for Spatiotemporal Composability_](https://github.com/cordiverse/paper)。
+
+## 开发者预览
+
+DeepSeek Harness 目前处于 _开发者预览_ 阶段，正在快速迭代。**未来将出现破坏兼容性的变更。**
+
+## 运行
+
+### 通过 `npm` 运行
+
+安装 `Node.js`，然后运行：
+
+```sh
+npx @deepseek-ai/dsh web
+```
+
+该命令会启动 Web UI，默认地址为 `http://127.0.0.1:3080`。详见 [Web UI 指南](docs/user/guide/index.md)。
+
+### 从源码运行
+
+如需从仓库源码运行：
+
+```sh
+git clone https://github.com/deepseek-ai/deepseek-harness.git
+cd deepseek-harness
+pnpm install
+pnpm run build
+pnpm dsh web
+```
+
+## 社区与支持
+
+- 欢迎通过 [GitHub Discussions](https://github.com/deepseek-ai/deepseek-harness/discussions) 提交反馈或 bug 报告。
+- 为你的插件仓库添加 [`dsh-plugin`](https://github.com/topics/dsh-plugin) 话题，便于被发现。
+- 欢迎加入 DeepSeek Harness 企微群：扫码添加企微小助手并填写入群问卷，完成后小助手会邀请你入群。
+
+<table>
+  <thead>
+    <tr>
+      <th align="center">企微小助手</th>
+      <th align="center">入群问卷</th>
+      <th align="center">微信公众号</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td align="center"><img src="assets/community-wecom-assistant.png" alt="DeepSeek Harness 企微小助手二维码" width="180" height="180"></td>
+      <td align="center"><a href="https://trtgsjkv6r.feishu.cn/share/base/form/shrcnIt5twSVdLGD52KJBckGCgg"><img src="assets/community-wecom-survey.png" alt="DeepSeek Harness 入群问卷二维码" width="180" height="180"></a></td>
+      <td align="center"><img src="assets/community-wechat-official-account.png" alt="DeepSeek Harness 团队微信公众号二维码" width="180" height="180"></td>
+    </tr>
+  </tbody>
+</table>
+
+## 参与贡献
+
+参见 [CONTRIBUTING.md](CONTRIBUTING.md)。
+
+## 开发
+
+请先阅读[开发指南](docs/development.md)与[架构文档](docs/architecture.md)。
+
+面向 agent：请遵循 [AGENTS.md](AGENTS.md)。
+
+## 许可证
+
+[MIT](LICENSE)
+
+第三方依赖及其许可证见 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。

package/references/official-docs/SNAPSHOT.md

@@ -0,0 +1,16 @@
+# official-docs snapshot (SNAPSHOT.md)
+
+> Generated by `scripts/sync-official-docs.ps1`. This file is the single authority for how `references/official-docs/` lines up with upstream deepseek-harness.
+> The "last verified" dates and commit SHAs in README/guide must cite this file; do not hand-edit them.
+
+| Item | Value |
+|---|---|
+| Source checkout | `D:\deepseek-harness` |
+| Source ref | `origin/master` |
+| Source commit | `47f943859bef60e4160492346772ded9b24f765a` |
+| Synced at (UTC) | 2026-08-14T15:13:50Z |
+| Scope | tracked files at the ref: `docs/`, root `AGENTS.md`, `BENCHMARK.md`, `CLAUDE.md`(symlink 目标文本), `CONTRIBUTING.md`/`.zh.md`/`.i18n.yaml`, `README.zh.md`/`.i18n.yaml`（上游英文 `README.md` 不在本目录，快照见 `downloads/github/harness/README.md`）, `THIRD_PARTY_NOTICES.md`, `LICENSE`, `packages/AGENTS.md`, `examples/AGENTS.md`, `packages/README.md`, `vendor/README.md`, `website/docs.ts` |
+| File counts | docs/: 215 md files (105 .zh.md pairs) |
+| Pruned this run | 107 个不在范围内/上游已删除的条目 |
+
+Drift check: `pwsh -File scripts/verify-kit.ps1 -Checkout <checkout>` (tracked files only).

package/references/official-docs/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,192 @@
+<!-- Generated by scripts/gen-third-party-notices.ts — do not edit by hand.
+     Run `pnpm run gen-third-party-notices` to regenerate. -->
+
+# Third-Party Notices
+
+DeepSeek Harness is licensed under [MIT](LICENSE). It depends on the third-party software listed below. Each project remains under its own license; nothing in this file changes those terms.
+
+This file lists **direct** dependencies declared by the workspace and the explicitly disclosed official Claude platform payload closure. It is generated from the workspace manifests by `scripts/gen-third-party-notices.ts`: a pre-commit hook regenerates it whenever a staged file changes one of its inputs, and `scripts/gen-third-party-notices.spec.ts` asserts in the test lane that the committed bytes match. Deleting a manifest runs no hook, so that case is caught by the assertion instead. Run `pnpm run verify-third-party-notices` for the standalone check.
+
+The complete npm transitive closure, including the Landlock launcher workspace, is recorded with exact pinned versions in [`pnpm-lock.yaml`](pnpm-lock.yaml) — inspect it with `pnpm licenses list`. The Python closure is recorded separately in [`python/sdk/uv.lock`](python/sdk/uv.lock).
+
+## Vendored source (`vendor/`)
+
+The Cordis framework and its foundation libraries are source-vendored into this repository rather than consumed from npm, and republished under the `@deepseek-ai` scope. All are MIT-licensed; each directory preserves its upstream `LICENSE` file. Exact upstream commits and local modifications are recorded in [`vendor/README.md`](vendor/README.md).
+
+| Package | Upstream name | Upstream | License |
+| --- | --- | --- | --- |
+| `@deepseek-ai/cosmokit` | `cosmokit` | [github.com/deepseek-harness/cosmokit](https://github.com/deepseek-harness/cosmokit) | MIT |
+| `@deepseek-ai/schemastery` | `schemastery` | [github.com/deepseek-harness/schemastery](https://github.com/deepseek-harness/schemastery) | MIT |
+| `@deepseek-ai/cordis` | `cordis` | [github.com/cordiverse/cordis](https://github.com/cordiverse/cordis) | MIT |
+| `@deepseek-ai/cordis-plugin-loader` | `@cordisjs/plugin-loader` | [github.com/cordiverse/cordis](https://github.com/cordiverse/cordis) | MIT |
+| `@deepseek-ai/cordis-plugin-include` | `@cordisjs/plugin-include` | [github.com/deepseek-harness/cordis](https://github.com/deepseek-harness/cordis) | MIT |
+| `@deepseek-ai/cordis-plugin-group` | `@cordisjs/plugin-group` | [github.com/deepseek-harness/cordis](https://github.com/deepseek-harness/cordis) | MIT |
+| `@deepseek-ai/cordis-plugin-timer` | `@cordisjs/plugin-timer` | [github.com/deepseek-harness/cordis](https://github.com/deepseek-harness/cordis) | MIT |
+| `@deepseek-ai/cordis-plugin-hmr` | `@cordisjs/plugin-hmr` | [github.com/deepseek-harness/cordis](https://github.com/deepseek-harness/cordis) | MIT |
+| `@deepseek-ai/cordis-plugin-logger-console` | `@cordisjs/plugin-logger-console` | [github.com/deepseek-harness/cordis](https://github.com/deepseek-harness/cordis) | MIT |
+
+## Runtime npm dependencies
+
+External packages that a workspace package resolves at runtime. The tier covers every plugin a user can mount from `cordis.yml` — not only what the `dsh` CLI, Web UI, and Python SDK runtime load by default.
+
+| Package | License |
+| --- | --- |
+| [`@agentclientprotocol/sdk`](https://github.com/agentclientprotocol/typescript-sdk) | Apache-2.0 |
+| [`@anthropic-ai/claude-agent-sdk`](https://github.com/anthropics/claude-agent-sdk-typescript) | SEE LICENSE IN README.md |
+| [`@anthropic-ai/sdk`](https://github.com/anthropics/anthropic-sdk-typescript) | MIT |
+| [`@babel/code-frame`](https://github.com/babel/babel) | MIT |
+| [`@earendil-works/pi-ai`](https://github.com/earendil-works/pi) | MIT |
+| [`@joplin/turndown-plugin-gfm`](https://github.com/laurent22/joplin-turndown-plugin-gfm) | MIT |
+| [`@jridgewell/gen-mapping`](https://github.com/jridgewell/sourcemaps) | MIT |
+| [`@modelcontextprotocol/sdk`](https://github.com/modelcontextprotocol/typescript-sdk) | MIT |
+| [`@opentelemetry/api`](https://github.com/open-telemetry/opentelemetry-js) | Apache-2.0 |
+| [`@opentelemetry/api-logs`](https://github.com/open-telemetry/opentelemetry-js) | Apache-2.0 |
+| [`@opentelemetry/exporter-logs-otlp-http`](https://github.com/open-telemetry/opentelemetry-js) | Apache-2.0 |
+| [`@opentelemetry/otlp-exporter-base`](https://github.com/open-telemetry/opentelemetry-js) | Apache-2.0 |
+| [`@opentelemetry/resources`](https://github.com/open-telemetry/opentelemetry-js) | Apache-2.0 |
+| [`@opentelemetry/sdk-logs`](https://github.com/open-telemetry/opentelemetry-js) | Apache-2.0 |
+| [`@shikijs/langs`](https://github.com/shikijs/shiki) | MIT |
+| [`@standard-schema/spec`](https://github.com/standard-schema/standard-schema) | MIT |
+| [`@tanstack/react-virtual`](https://github.com/TanStack/virtual) | MIT |
+| [`@types/mdast`](https://github.com/DefinitelyTyped/DefinitelyTyped) | MIT |
+| [`@vscode/ripgrep`](https://github.com/microsoft/vscode-ripgrep) | MIT |
+| [`anser`](https://github.com/IonicaBizau/anser) | MIT |
+| [`chokidar`](https://github.com/paulmillr/chokidar) | MIT |
+| [`clsx`](https://github.com/lukeed/clsx) | MIT |
+| [`commander`](https://github.com/tj/commander.js) | MIT |
+| [`diff`](https://github.com/kpdecker/jsdiff) | BSD-3-Clause |
+| [`e2b`](https://github.com/e2b-dev/e2b) | MIT |
+| [`eventsource-parser`](https://github.com/rexxars/eventsource-parser) | MIT |
+| [`fflate`](https://github.com/101arrowz/fflate) | MIT |
+| [`immer`](https://github.com/immerjs/immer) | MIT |
+| [`js-yaml`](https://github.com/nodeca/js-yaml) | MIT |
+| [`katex`](https://github.com/KaTeX/KaTeX) | MIT |
+| [`koffi`](https://github.com/Koromix/koffi) | MIT |
+| [`mdast-util-from-markdown`](https://github.com/syntax-tree/mdast-util-from-markdown) | MIT |
+| [`mdast-util-gfm`](https://github.com/syntax-tree/mdast-util-gfm) | MIT |
+| [`mdast-util-math`](https://github.com/syntax-tree/mdast-util-math) | MIT |
+| [`micromark-core-commonmark`](https://github.com/micromark/micromark/tree/main/packages/micromark-core-commonmark) | MIT |
+| [`micromark-extension-gfm`](https://github.com/micromark/micromark-extension-gfm) | MIT |
+| [`micromark-extension-math`](https://github.com/micromark/micromark-extension-math) | MIT |
+| [`micromark-factory-space`](https://github.com/micromark/micromark/tree/main/packages/micromark-factory-space) | MIT |
+| [`micromark-util-character`](https://github.com/micromark/micromark/tree/main/packages/micromark-util-character) | MIT |
+| [`micromark-util-classify-character`](https://github.com/micromark/micromark/tree/main/packages/micromark-util-classify-character) | MIT |
+| [`micromark-util-sanitize-uri`](https://github.com/micromark/micromark/tree/main/packages/micromark-util-sanitize-uri) | MIT |
+| [`micromark-util-symbol`](https://github.com/micromark/micromark/tree/main/packages/micromark-util-symbol) | MIT |
+| [`micromark-util-types`](https://github.com/micromark/micromark/tree/main/packages/micromark-util-types) | MIT |
+| [`node-addon-require-builtin`](https://www.npmjs.com/package/node-addon-require-builtin) | MIT |
+| [`node-pty`](https://github.com/microsoft/node-pty) | MIT |
+| [`picomatch`](https://github.com/micromatch/picomatch) | MIT |
+| [`react`](https://github.com/facebook/react) | MIT |
+| [`react-dom`](https://github.com/facebook/react) | MIT |
+| [`sharp`](https://github.com/lovell/sharp) | Apache-2.0 |
+| [`shiki`](https://github.com/shikijs/shiki) | MIT |
+| [`supports-color`](https://github.com/chalk/supports-color) | MIT |
+| [`tsx`](https://github.com/privatenumber/tsx) | MIT |
+| [`turndown`](https://github.com/mixmark-io/turndown) | MIT |
+| [`typescript`](https://github.com/microsoft/TypeScript) | Apache-2.0 |
+| [`use-sync-external-store`](https://github.com/facebook/react) | MIT |
+| [`ws`](https://github.com/websockets/ws) | MIT |
+| [`yaml`](https://github.com/eemeli/yaml) | ISC |
+| [`zod`](https://github.com/colinhacks/zod) | MIT |
+| [`zustand`](https://github.com/pmndrs/zustand) | MIT |
+
+pnpm applies local patches to the following packages at install time, so shipped artifacts carry modified copies; each patch file is the complete record of the modification:
+
+- `node-pty@1.1.0` — [`patches/node-pty@1.1.0.patch`](patches/node-pty@1.1.0.patch)
+
+## Official Claude Code platform payloads
+
+The project owner authorizes distribution of every version of the official `@anthropic-ai/claude-agent-sdk` package and the official Claude Code CLI/platform payloads that each version declares through `optionalDependencies`. This identity-scoped authorization does not classify their declared terms as permissive and does not cover any unrelated runtime package; version, declared-license, and payload-set changes still require the ordinary dependency, lockfile, compatibility, terms, and notices review.
+
+The installed SDK 0.3.220 declares the following optional platform packages. Each carries the official Claude Code 2.1.220 executable; the package identities and versions come from the SDK manifest, while the declared license field is verified against the platform payload installed for the current host.
+
+| Optional platform package | Version | Declared license |
+| --- | --- | --- |
+| [`@anthropic-ai/claude-agent-sdk-darwin-arm64`](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk-darwin-arm64) | 0.3.220 | SEE LICENSE IN LICENSE.md |
+| [`@anthropic-ai/claude-agent-sdk-darwin-x64`](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk-darwin-x64) | 0.3.220 | SEE LICENSE IN LICENSE.md |
+| [`@anthropic-ai/claude-agent-sdk-linux-arm64`](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk-linux-arm64) | 0.3.220 | SEE LICENSE IN LICENSE.md |
+| [`@anthropic-ai/claude-agent-sdk-linux-arm64-musl`](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk-linux-arm64-musl) | 0.3.220 | SEE LICENSE IN LICENSE.md |
+| [`@anthropic-ai/claude-agent-sdk-linux-x64`](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk-linux-x64) | 0.3.220 | SEE LICENSE IN LICENSE.md |
+| [`@anthropic-ai/claude-agent-sdk-linux-x64-musl`](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk-linux-x64-musl) | 0.3.220 | SEE LICENSE IN LICENSE.md |
+| [`@anthropic-ai/claude-agent-sdk-win32-arm64`](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk-win32-arm64) | 0.3.220 | SEE LICENSE IN LICENSE.md |
+| [`@anthropic-ai/claude-agent-sdk-win32-x64`](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk-win32-x64) | 0.3.220 | SEE LICENSE IN LICENSE.md |
+
+
+## Development-only npm dependencies
+
+External packages **directly declared** only by repository tooling, test infrastructure, the documentation site, the demo leaves, or the native launcher's build workspace. No shipped surface names them itself. A package here may still be pulled in transitively by a runtime dependency — `pnpm-lock.yaml` is the authority on the full closure — so this tier records who declares a package, not what a build ultimately bundles.
+
+| Package | License |
+| --- | --- |
+| [`@braintree/sanitize-url`](https://github.com/braintree/sanitize-url) | MIT |
+| [`@modelcontextprotocol/server-everything`](https://github.com/modelcontextprotocol/servers) | MIT / Apache-2.0 |
+| [`@modelcontextprotocol/server-filesystem`](https://github.com/modelcontextprotocol/servers) | MIT / Apache-2.0 |
+| [`@openai/codex`](https://github.com/openai/codex) | Apache-2.0 |
+| [`@stylistic/eslint-plugin`](https://github.com/eslint-stylistic/eslint-stylistic) | MIT |
+| [`@testing-library/dom`](https://github.com/testing-library/dom-testing-library) | MIT |
+| [`@testing-library/react`](https://github.com/testing-library/react-testing-library) | MIT |
+| [`@types/babel__code-frame`](https://github.com/DefinitelyTyped/DefinitelyTyped) | MIT |
+| [`@types/js-yaml`](https://github.com/DefinitelyTyped/DefinitelyTyped) | MIT |
+| [`@types/jsdom`](https://github.com/DefinitelyTyped/DefinitelyTyped) | MIT |
+| [`@types/node`](https://github.com/DefinitelyTyped/DefinitelyTyped) | MIT |
+| [`@types/picomatch`](https://github.com/DefinitelyTyped/DefinitelyTyped) | MIT |
+| [`@types/react`](https://github.com/DefinitelyTyped/DefinitelyTyped) | MIT |
+| [`@types/react-dom`](https://github.com/DefinitelyTyped/DefinitelyTyped) | MIT |
+| [`@types/spdx-expression-parse`](https://github.com/DefinitelyTyped/DefinitelyTyped) | MIT |
+| [`@types/turndown`](https://github.com/DefinitelyTyped/DefinitelyTyped) | MIT |
+| [`@types/ws`](https://github.com/DefinitelyTyped/DefinitelyTyped) | MIT |
+| [`@vitejs/plugin-react`](https://github.com/vitejs/vite-plugin-react) | MIT |
+| [`@vitest/coverage-v8`](https://github.com/vitest-dev/vitest) | MIT |
+| [`@yarnpkg/cli-dist`](https://github.com/yarnpkg/berry) | BSD-2-Clause |
+| [`cytoscape`](https://github.com/cytoscape/cytoscape.js) | MIT |
+| [`cytoscape-cose-bilkent`](https://github.com/cytoscape/cytoscape.js-cose-bilkent) | MIT |
+| [`dayjs`](https://github.com/iamkun/dayjs) | MIT |
+| [`debug`](https://github.com/debug-js/debug) | MIT |
+| [`esbuild`](https://github.com/evanw/esbuild) | MIT |
+| [`eslint-plugin-sonarjs`](https://github.com/SonarSource/SonarJS) | LGPL-3.0-only |
+| [`execa`](https://github.com/sindresorhus/execa) | MIT |
+| [`fast-check`](https://github.com/dubzzz/fast-check) | MIT |
+| [`istanbul-lib-report`](https://github.com/istanbuljs/istanbuljs) | BSD-3-Clause |
+| [`jscpd`](https://github.com/kucherenko/jscpd) | MIT |
+| [`jsdom`](https://github.com/jsdom/jsdom) | MIT |
+| [`knip`](https://github.com/webpro-nl/knip) | ISC |
+| [`lefthook`](https://github.com/evilmartians/lefthook) | MIT |
+| [`lightningcss`](https://github.com/parcel-bundler/lightningcss) | MPL-2.0 |
+| [`mermaid`](https://github.com/mermaid-js/mermaid) | MIT |
+| [`oxlint`](https://github.com/oxc-project/oxc) | MIT |
+| [`oxlint-tsgolint`](https://github.com/oxc-project/tsgolint) | MIT |
+| [`playwright`](https://github.com/microsoft/playwright) | Apache-2.0 |
+| [`publint`](https://github.com/publint/publint) | MIT |
+| [`smol-toml`](https://github.com/squirrelchat/smol-toml) | BSD-3-Clause |
+| [`spdx-expression-parse`](https://github.com/jslicense/spdx-expression-parse.js) | MIT |
+| [`tsdown`](https://github.com/rolldown/tsdown) | MIT |
+| [`typescript-language-server`](https://github.com/typescript-language-server/typescript-language-server) | Apache-2.0 |
+| [`vite`](https://github.com/vitejs/vite) | MIT |
+| [`vite-tsconfig-paths`](https://github.com/aleclarson/vite-tsconfig-paths) | MIT |
+| [`vitepress`](https://github.com/vuejs/vitepress) | MIT |
+| [`vitepress-plugin-mermaid`](https://github.com/emersonbottero/vitepress-plugin-mermaid) | MIT |
+| [`vitest`](https://github.com/vitest-dev/vitest) | MIT |
+
+`eslint-plugin-sonarjs` (LGPL-3.0-only) and `lightningcss` (MPL-2.0) run only as development tooling; their code is not linked into or distributed with any DeepSeek Harness artifact.
+
+## Python SDK dependencies (`python/`)
+
+Direct dependencies of the `pyproject.toml` manifests, plus `uv` as the development workflow tool.
+
+| Package | License | Role |
+| --- | --- | --- |
+| [`hatchling`](https://github.com/pypa/hatch) | MIT | build backend |
+| [`pydantic`](https://github.com/pydantic/pydantic) | MIT | runtime dependency of `deepseek-harness-sdk` |
+| [`pytest`](https://github.com/pytest-dev/pytest) | MIT | test-only |
+| [`uv`](https://github.com/astral-sh/uv) | MIT / Apache-2.0 | development workflow tool |
+
+## Fetched at build time
+
+| Package | License | Role |
+| --- | --- | --- |
+| [`@yao-pkg/pkg`](https://github.com/yao-pkg/pkg) | MIT | invoked by `scripts/build-exe-for-python-sdk.ts` to assemble the single-file SDK runtime executable |
+
+## First-party native packages
+
+`@deepseek-ai/node-addon-landlock-run` (and its platform packages) is built and released from this repository under BSD 3-Clause. It is listed here for completeness; it is first-party, not third-party.