mirror of
https://github.com/deepseek-ai/deepseek-harness
synced 2026-08-15 21:04:50 +00:00
Merge branch 'master' into codex/cli-one-shot-demo
This commit is contained in:
Tianyi Cui
GitHub
@@ -181,7 +181,7 @@ export interface Config extends LocalConfig {
|
||||
|
||||
Depends on: [`LocalConfig`](#deepseek-aidsh-bash-local) · [`SandboxMode`](core-data-structures/sandbox.md)
|
||||
|
||||
Source: [`packages/bash/bash-sandbox/src/index.ts:26`](../packages/bash/bash-sandbox/src/index.ts)
|
||||
Source: [`packages/bash/bash-sandbox/src/index.ts:27`](../packages/bash/bash-sandbox/src/index.ts)
|
||||
|
||||
## `@deepseek-ai/dsh-cli-demo`
|
||||
|
||||
@@ -598,7 +598,7 @@ export interface Config {
|
||||
}
|
||||
```
|
||||
|
||||
Source: [`packages/sandbox/sandbox-local/src/index.ts:20`](../packages/sandbox/sandbox-local/src/index.ts)
|
||||
Source: [`packages/sandbox/sandbox-local/src/index.ts:19`](../packages/sandbox/sandbox-local/src/index.ts)
|
||||
|
||||
## `@deepseek-ai/dsh-session-persistence-jsonl`
|
||||
|
||||
@@ -1301,13 +1301,16 @@ Abstract service classes — a deployment loads a concrete implementation packag
|
||||
|
||||
Imported as libraries by other packages; a `cordis.yml` cannot load them.
|
||||
|
||||
- `@deepseek-ai/create-sdk` ([`packages/sdk/create-sdk/src/index.ts`](../packages/sdk/create-sdk/src/index.ts))
|
||||
- `@deepseek-ai/dsh-acp-snapshot` ([`packages/support/acp-snapshot/src/index.ts`](../packages/support/acp-snapshot/src/index.ts))
|
||||
- `@deepseek-ai/dsh-app-boot` ([`packages/ui/app-boot/src/index.ts`](../packages/ui/app-boot/src/index.ts))
|
||||
- `@deepseek-ai/dsh-brand` ([`packages/util/brand/src/index.ts`](../packages/util/brand/src/index.ts))
|
||||
- `@deepseek-ai/dsh-helper` ([`packages/sdk/helper/src/index.ts`](../packages/sdk/helper/src/index.ts))
|
||||
- `@deepseek-ai/dsh-hook-protocol` ([`packages/hooks/hook-protocol/src/index.ts`](../packages/hooks/hook-protocol/src/index.ts))
|
||||
- `@deepseek-ai/dsh-jsonrpc-demo` ([`packages/examples/jsonrpc-demo/src/index.ts`](../packages/examples/jsonrpc-demo/src/index.ts))
|
||||
- `@deepseek-ai/dsh-loader-smoke` ([`packages/support/loader-smoke/src/index.ts`](../packages/support/loader-smoke/src/index.ts))
|
||||
- `@deepseek-ai/dsh-scope` ([`packages/core/scope/src/index.ts`](../packages/core/scope/src/index.ts))
|
||||
- `@deepseek-ai/dsh-scripts` ([`packages/sdk/scripts/src/index.ts`](../packages/sdk/scripts/src/index.ts))
|
||||
- `@deepseek-ai/dsh-subagent-inprocess` ([`packages/subagent/subagent-inprocess/src/index.ts`](../packages/subagent/subagent-inprocess/src/index.ts))
|
||||
- `@deepseek-ai/dsh-subagent-subprocess` ([`packages/subagent/subagent-subprocess/src/index.ts`](../packages/subagent/subagent-subprocess/src/index.ts))
|
||||
- `@deepseek-ai/dsh-timeout` ([`packages/util/timeout/src/index.ts`](../packages/util/timeout/src/index.ts))
|
||||
|
||||
@@ -78,12 +78,14 @@
|
||||
| block | 块 | | | |
|
||||
| build target | 构建目标 | | | |
|
||||
| cancel | 取消 | | | |
|
||||
| capability | 能力 | | | |
|
||||
| feature | 功能 | | 能力 | SDK 产品与工程模型中的可管理产品单元 |
|
||||
| feature option | 功能选项 | | variant | 一项 SDK 功能内有限、可选择的实现或配置 |
|
||||
| checkpoint | 检查点 | | | |
|
||||
| chunk | 分片 | | | |
|
||||
| compaction | 压缩 | 压缩（compaction） | | |
|
||||
| companion tool | 配套工具 | | | |
|
||||
| config | 配置 | | | |
|
||||
| Cordis plugin config | Cordis 插件配置 | | | Cordis 插件公开的 `Config` 对象或配置结构 |
|
||||
| config key | 配置键 | | | Cordis 插件配置中的单个字段 |
|
||||
| consumer | 消费方 | | | |
|
||||
| content block | 内容块 | | | |
|
||||
| Cookbook | 实操手册 | | | 文档标题用语 |
|
||||
@@ -91,10 +93,13 @@
|
||||
| counterpart | 对侧文件 | | 对应物、配对物 | 双语配对语境；泛指"另一侧"时可写「另一侧」 |
|
||||
| context compaction | 上下文压缩 | 上下文压缩（context compaction） | | |
|
||||
| contract | 契约 | | | 如：`pairing contract` →`配对契约` |
|
||||
| Cordis config entry | Cordis 配置项 | | | 指 `cordis.yml` 插件列表中的一项；插件实现本身写`Cordis 插件` |
|
||||
| Cordis plugin | Cordis 插件 | | | Cordis 加载的插件实现，不指 `cordis.yml` 中的一项配置 |
|
||||
| coverage | 覆盖率 | | | |
|
||||
| crash recovery | 崩溃恢复 | | | |
|
||||
| deploy root | 部署根目录 | | | |
|
||||
| durability | 持久性 | | | |
|
||||
| feature requirement | 功能依赖 | | | 功能或功能选项通过 `requires` 声明的关系 |
|
||||
| enforcement frontier | 执行红线 | | 强制边界 | i18n 配对机制用语：manifest `required` 清单所划的门禁生效范围；与金标样例（style-samples ⑦）一致 |
|
||||
| event | 事件 | | | |
|
||||
| event log | 事件日志 | | | |
|
||||
@@ -123,6 +128,7 @@
|
||||
| mod | 模组 | | | |
|
||||
| model provider | 模型提供方 | | | |
|
||||
| module | 模块 | | | |
|
||||
| npm dependency | NPM 依赖 | | | `package.json` 中的包关系；`dependencies`、`devDependencies` 等字段保持原样 |
|
||||
| orphan | 遗留 | | 孤儿、孤立 | 指英文源已不存在的 `.zh.md`（如「遗留译文」）；进程语境按 OS 惯用语译「孤儿进程」 |
|
||||
| orphan branch | 孤立分支 | | 孤儿分支 | 沿用 git 官方中文翻译 |
|
||||
| package | 包 | 包（package） | | 指 npm 包（`@deepseek-ai/dsh-*`）；`package.json` 等代码标识保持原样 |
|
||||
|
||||
@@ -125,6 +125,10 @@ flowchart TD
|
||||
pkg_sandbox["sandbox"]
|
||||
pkg_sandbox_local["sandbox-local"]
|
||||
end
|
||||
subgraph group_sdk["packages/sdk"]
|
||||
pkg_helper["helper"]
|
||||
pkg_scripts["scripts"]
|
||||
end
|
||||
subgraph group_tasks["packages/tasks"]
|
||||
pkg_tasks["tasks"]
|
||||
pkg_tool_tasks["tool-tasks"]
|
||||
@@ -136,6 +140,8 @@ flowchart TD
|
||||
end
|
||||
pkg_llm --> pkg_brand
|
||||
pkg_code_runtime_worker --> pkg_code_runtime
|
||||
pkg_helper --> pkg_brand
|
||||
pkg_scripts --> pkg_app_boot
|
||||
pkg_llm_deepseek --> pkg_llm
|
||||
pkg_llm_pi_ai --> pkg_llm
|
||||
pkg_session --> pkg_brand
|
||||
@@ -389,6 +395,8 @@ flowchart TD
|
||||
| [`jsonrpc-demo`](../packages/examples/jsonrpc-demo) | `examples` | — |
|
||||
| [`llm`](../packages/llm/llm) | `llm` | [`brand`](../packages/util/brand) |
|
||||
| [`code-runtime-worker`](../packages/code-runtime/code-runtime-worker) | `code-runtime` | [`code-runtime`](../packages/code-runtime/code-runtime) |
|
||||
| [`helper`](../packages/sdk/helper) | `sdk` | [`brand`](../packages/util/brand) |
|
||||
| [`scripts`](../packages/sdk/scripts) | `sdk` | [`app-boot`](../packages/ui/app-boot) |
|
||||
| [`llm-deepseek`](../packages/llm/llm-deepseek) | `llm` | [`llm`](../packages/llm/llm) |
|
||||
| [`llm-pi-ai`](../packages/llm/llm-pi-ai) | `llm` | [`llm`](../packages/llm/llm) |
|
||||
| [`session`](../packages/core/session) | `core` | [`brand`](../packages/util/brand), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope) |
|
||||
|
||||
@@ -13,6 +13,7 @@ Generated by `pnpm run gen-rfc-index` from the RFC tree — never edit by hand;
|
||||
| [Interactive side sessions and merge-back](proposed/feature/2026-07-08-interactive-side-sessions.md) | 2026-07-08 |
|
||||
| [SQLite FTS5 session search](proposed/feature/2026-07-10-sqlite-session-query-provider.md) | 2026-07-10 |
|
||||
| [Stream workflow progress through tool calls](proposed/feature/2026-07-13-stream-workflow-progress-through-tool-calls.md) | 2026-07-13 |
|
||||
| [Developer-owned SDK projects](proposed/feature/2026-07-14-sdk-developer-projects.md) | 2026-07-14 |
|
||||
|
||||
### Simplification
|
||||
|
||||
@@ -27,6 +28,7 @@ Generated by `pnpm run gen-rfc-index` from the RFC tree — never edit by hand;
|
||||
| Title | First proposed |
|
||||
|---|---|
|
||||
| [Runtime schemas for the event vocabulary (Zod vs the merge-extensible-map pattern)](proposed/architecture/2026-06-16-typed-event-schemas.md) | 2026-06-16 |
|
||||
| [SDK project editing architecture](proposed/architecture/2026-07-15-sdk-project-editing-architecture.md) | 2026-07-15 |
|
||||
|
||||
### Process
|
||||
|
||||
|
||||
@@ -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
|
||||
2026-07-15-sdk-project-editing-architecture.md: 985cc22c159c68801b78262aa96c7422bdfa1318
|
||||
2026-07-15-sdk-project-editing-architecture.zh.md: 6a194e8e5f193e62bfc283fd93a5fde0367fe196
|
||||
@@ -0,0 +1,129 @@
|
||||
# RFC: SDK project editing architecture
|
||||
|
||||
Status: proposed
|
||||
|
||||
English | [中文](2026-07-15-sdk-project-editing-architecture.zh.md)
|
||||
|
||||
## Problem
|
||||
|
||||
[Developer-owned SDK projects](../feature/2026-07-14-sdk-developer-projects.md) are created through create, adjusted through config, and built and run through commands such as start. Initial creation, configuration changes, and build and runtime commands all need to understand features, feature options, npm dependencies, Cordis config entries, environment variables, package managers, local plugins, and several project files. If each project-reading and project-writing workflow uses a separate interpretation protocol, the SDK developer workflows become difficult to maintain.
|
||||
|
||||
## Proposal
|
||||
|
||||
The SDK uses one shared object-oriented project model. `SdkProject` is a read-only snapshot, and `ProjectEditSession` is the only mutation and commit boundary. Feature objects own their feature options, relationships, resource contributions, and current-state inspection. Create and config orchestrate only their respective user workflows and modify projects through the same domain operations.
|
||||
|
||||
Structured files are modified through document objects, while one-shot text artifacts are generated from complete templates. Questions are typed objects presented through clack. Diff calculation may remain an edit-session implementation detail, but it is not a public execution protocol that callers must assemble.
|
||||
|
||||
## Terminology
|
||||
|
||||
| Term | Usage in this RFC | Meaning |
|
||||
|---|---|---|
|
||||
| Feature | feature | A product unit curated and managed by the SDK; one feature may contain several feature options and contribute several Cordis config entries, npm dependencies, environment placeholders, and owned files |
|
||||
| Feature option | feature option | A finite selectable implementation or configuration shape within one feature; feature rules may make options fixed, exclusive, or additive |
|
||||
| Cordis plugin | Cordis plugin | A plugin implementation loaded by Cordis, usually exported by an npm package; it is not an item in `cordis.yml` |
|
||||
| Cordis config entry | Cordis config entry | One item in the `cordis.yml` plugin list, identified as an instance by `id` and referring to a Cordis plugin through `name` |
|
||||
| Cordis plugin config | Cordis plugin config | The configuration object or shape exposed by a Cordis plugin; an individual field owned and updated by a feature is a config key |
|
||||
| config key | config key | One field in Cordis plugin config; a feature updates only the config keys it declares as owned and preserves unknown config keys |
|
||||
| npm dependency | npm dependency | A package relationship in `package.json`; literal fields such as `dependencies` and `devDependencies` keep their names |
|
||||
| Feature requirement | feature requirement | A relationship declared through `requires` by a feature or feature option |
|
||||
|
||||
## Package boundaries
|
||||
|
||||
| Package | Responsibility | Does not own |
|
||||
|---|---|---|
|
||||
| `@deepseek-ai/dsh-helper` | Edit sessions, feature configuration, project-template rendering, package-manager adaptation, and prompt interaction adaptation | Booting Cordis applications or deciding create/config terminal workflows |
|
||||
| `@deepseek-ai/dsh-scripts` | `dsh-sdk start/dev/build/config`, process lifecycle, project entry loading, the config workflow, and its terminal-copy templates | Interpreting feature definitions directly or modifying YAML/JSON ASTs |
|
||||
| `@deepseek-ai/create-sdk` | Arguments, question order, initial project creation, installation finish, and terminal-copy templates for `npm create @deepseek-ai/sdk` | Becoming a generated project's runtime npm dependency or providing a library API |
|
||||
|
||||
`@deepseek-ai/create-sdk` is the only exception to the repository's `@deepseek-ai/dsh-*` naming rule. npm's scoped-initializer convention requires that package name for `npm create @deepseek-ai/sdk`. The exception is a repository architecture fact and does not add a third developer product entrypoint.
|
||||
|
||||
The three packages export only the narrow entrypoints consumed by adjacent layers and provide no `src/*` deep imports. The scripts library entrypoint and build-config subpath serve generated code and project build configuration, while the developer product contract remains the `dsh-sdk` commands.
|
||||
|
||||
## Project aggregate and edit session
|
||||
|
||||
`SdkProject.create(root, request)` constructs a new project snapshot that has not been written, while `SdkProject.open(root)` loads an existing project. Open requires only readable root `package.json` and `cordis.yml` files; every other file is an optional resource. Both paths return the same read-only aggregate and distinguish their source through explicit origin state.
|
||||
|
||||
`project.edit()` clones project documents into a working copy. Domain commands such as install, configure, enable, disable, and addPlugin modify only the working copy. Each command immediately re-inspects its owning feature, and the final commit checks all relationships and files again.
|
||||
|
||||
```text
|
||||
validate feature requirements and resource ownership
|
||||
-> validate every affected document
|
||||
-> compute changed and removed paths
|
||||
-> compare existing files with the session's original text
|
||||
-> write through one commit boundary
|
||||
-> return a new SdkProject snapshot and ChangeSet
|
||||
```
|
||||
|
||||
Validation failure or an external edit causes zero writes. “One commit” means only zero pre-write side effects and one write entrypoint. `ChangeSet` describes final feature, plugin, and file changes for Review & Apply and create completion.
|
||||
|
||||
## Features and resource ownership
|
||||
|
||||
A feature is a first-class behavior object. Shallow base classes implement install, configure, enable, disable, required/requires validation, and common state inspection. Features with fixed, exclusive, or additive feature options share these lifecycles. Only features whose resource contributions depend on project context or require custom round-tripping use dedicated behavior classes; other features declare their actual differences through standardized data.
|
||||
|
||||
Each feature contributes stable-keyed Cordis config entries, npm dependencies, environment placeholders, and owned files. The registry rejects two features that declare the same resource key during initialization. Different feature options within one feature may share resources, which that feature resolves from the final option set.
|
||||
|
||||
A Cordis config entry anchors feature installation. The npm package name assigns the entry to a feature, and the entry ID distinguishes several instances of one plugin package. An npm dependency without a feature-owned Cordis config entry leaves the feature uninstalled. Once a Cordis config entry exists, a missing npm dependency, unreadable Cordis plugin config, or resource conflict puts the feature into an inconsistent state; the config command shows diagnostics and refuses speculative modification.
|
||||
|
||||
Configuring the same feature option updates only its owned config keys and preserves unknown keys. Replacing a feature option removes old resources that are exclusive and still confirmable. If an old resource cannot be confirmed or an owned file was modified by the developer, the whole operation fails.
|
||||
|
||||
## Questions and workflows
|
||||
|
||||
TypeScript `Question<T>` objects keep defaults, validation, applicability, and types together. `PromptPort` is the only interface between the domain layer and the terminal library, and helper provides one thin `ClackPromptPort`. Create and config inject their own command-line input and output streams and retain ownership of cancellation, return, and completion semantics in their workflows.
|
||||
|
||||
Create keeps its stateful question order in one wizard, while config keeps final-state selection in one workflow. Both use the same feature configurator for feature options and dedicated inputs, so adding an ordinary feature, feature option, or parameter does not require changes to both entrypoints.
|
||||
|
||||
## Project documents and templates
|
||||
|
||||
Only structured files that helper reads or modifies have concrete document objects: `package.json`, `cordis.yml`, `.env`, `.env.example`, the root `tsconfig.json`, and the pnpm workspace file. Document objects own parsing, cloning, validation, and serialization. Concrete classes and modules use `*File` and `*-file.ts` names respectively. Business code does not manipulate YAML/JSON ASTs directly, and malformed shapes fail loudly at the owning document boundary.
|
||||
|
||||
README, entrypoint code, build configuration, `.gitignore`, and other one-shot text artifacts use one complete template per real file. Complete product copy such as CLI usage, creation and recovery messages, installation and retry guidance, and the default persona also comes from package-local templates owned by the package that presents it.
|
||||
|
||||
Helper provides the generic typed `TextTemplate` renderer, and caller packages load their own templates through package-local asset URLs.
|
||||
|
||||
Templates use Handlebars strict mode and `noEscape` without custom processing. File owners encode typed values for the target language. Template source escapes interpolation as `\{{model}}` when it must emit the downstream literal unchanged.
|
||||
|
||||
## Command and runtime boundary
|
||||
|
||||
Scripts supports `dsh-sdk start/dev/build/config`. Start dynamically loads a module target and calls its named entrypoint. Dev adds TypeScript and local-workspace source resolution before following the same path. Build invokes the project's installed tsdown. Config opens one edit session and commits after Review & Apply. Generated projects run `tsc -b` directly for typechecking.
|
||||
|
||||
HMR is an explicit Cordis config entry loaded by dev and start. Its required `node-addon-require-builtin` package is supplied transitively by the scripts package and is absent from the generated project's `package.json`.
|
||||
|
||||
Dev and start execute the developer entrypoint, where developer code handles command-line arguments and cwd. Developers pass `--model=<name>` and `--resume=<session-id>` to start the standard flow.
|
||||
|
||||
## Repository live-link mode
|
||||
|
||||
Create-sdk retains a hidden `--link-workspace` option for Harness repository development and e2e. The parser accepts it, but help, public flag lists, and ordinary user documentation omit it. It accepts no repository-path parameter; the repository root is derived upward from the executing create-sdk module.
|
||||
|
||||
Link mode preserves the ordinary project file shape. `@deepseek-ai/*` points into `packages/`, Cordis-related npm dependencies point into `vendor/`, and shared lower-level packages resolve to the same physical copy used by the repository so Cordis type merging cannot produce multiple module type definitions. npm uses `file:`, pnpm uses `link:` with automatic peer installation disabled, and Yarn uses `portal:` plus resolutions. Repository packages must be built first.
|
||||
|
||||
## Future work
|
||||
|
||||
- **Replaceable required spine roles.** The current `spine` owns the full implementation set, including SystemPrompt and LLMService, through one fixed feature option. Developers cannot replace or switch these roles and must edit Cordis config entries manually.
|
||||
- **Service contracts and package declarations.** When replacing a builtin service, a Cordis plugin currently cannot declare the services it provides through `provides` metadata, so the SDK cannot assist configuration during development or check compatibility at runtime. A corresponding protocol remains to be designed.
|
||||
- **Feature parameter descriptions.** Feature-specific inputs currently require handwritten declarations. The SDK cannot derive interactive parameters automatically from arbitrary Cordis plugin config or npm package.json information. Future declarative metadata may expose a limited parameter set without turning arbitrary Cordis plugin config into a generic form.
|
||||
- **SDK application-level configuration.** The current project resource model describes Cordis config entries and config keys owned by individual Cordis plugins, so every SDK-managed setting must belong to one plugin. Cross-plugin or whole-application settings have no independent persistence location. Future work must define an application-level configuration document and its ownership, read, and mutation boundaries.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
**Keep the static Catalog and central engine.** This minimizes the initial rewrite, but feature parameters, round-tripping, owned files, and create/config reuse continue to accumulate in one coordinator. Splitting files shortens the file without consolidating responsibility.
|
||||
|
||||
**Use `wizard.json` and a generic Questionnaire.** Static forms cannot directly express feature requirements, option switches, existing-value refill, and project-resource changes. Types, gates, and dynamic options still connect through string registries and a procedural `run()`, creating another internal DSL.
|
||||
|
||||
**Expose the live-link flag.** The mode depends on Harness monorepo layout and unpublished packages and serves repository development only. Making it public would create a project-creation contract that the SDK cannot support outside the repository.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- Create and config modify projects only through `SdkProject` and `ProjectEditSession`; any business, document, or concurrency validation failure before writing leaves the filesystem unchanged
|
||||
- Adding an ordinary feature, feature option, or parameter extends only its typed spec or owning behavior object, without adding a central switch to create or config workflows
|
||||
- Helper owns the feature model, npm dependency and other resource configuration, and inconsistent-state detection
|
||||
- Structured files change through `*File` document objects; one-shot files and complete product copy come from package-owned Handlebars templates, and business decisions do not enter a template DSL
|
||||
- `dsh-sdk start/dev/build/config` is the runtime product surface, typecheck uses `tsc -b` directly, HMR is not injected by command mode, and only the scripts package transitively supplies `node-addon-require-builtin`
|
||||
- `--link-workspace` exists only as a hidden repository-development option and preserves one module identity under npm, pnpm, and Yarn
|
||||
|
||||
## Risks
|
||||
|
||||
- Behavior objects and typed specs create two extension shapes. Dedicated classes must remain limited to features that truly depend on project context or custom behavior, or the design will grow a meaningless type hierarchy
|
||||
- Optimistic concurrency checks and pre-write validation cannot recover from an I/O failure during writing; callers must still report a possible partial commit to the developer
|
||||
- Hidden link mode depends on repository layout and package-manager link semantics and must change with either one
|
||||
- The Cordis loader resolves `node-addon-require-builtin` from its own module path, so the scripts package must continue to satisfy that optional peer under npm, pnpm, and Yarn npm dependency layouts
|
||||
- Handlebars `noEscape` makes typed model construction responsible for target-language encoding; new template fields must be escaped correctly at the owning boundary, and downstream Handlebars placeholders must be escaped explicitly in template source
|
||||
@@ -0,0 +1,129 @@
|
||||
# RFC: SDK 工程编辑架构
|
||||
|
||||
Status: proposed
|
||||
|
||||
[English](2026-07-15-sdk-project-editing-architecture.md) | 中文
|
||||
|
||||
## 问题
|
||||
|
||||
[开发者拥有的 SDK 工程](../feature/2026-07-14-sdk-developer-projects.md) 由 create 创建，可以通过 config 调整，并由 start 等命令构建和运行。初始创建、配置调整和编译运行都需要理解功能、功能选项、NPM 依赖、Cordis 配置项、环境变量、包管理器、本地插件和多个项目文件。如果读写项目的各个流程分别使用不同的解析协议，SDK 开发者流程会变得难以维护。
|
||||
|
||||
## 提案
|
||||
|
||||
SDK 使用一个共享的面向对象工程模型。`SdkProject` 是只读快照，`ProjectEditSession` 是唯一修改与提交边界；功能对象负责自身的功能选项、关系、资源贡献和现状识别；create 与 config 只编排各自的用户流程，并通过同一组领域操作修改工程。
|
||||
|
||||
结构化文件通过文档对象修改，一次性文本产物通过完整模板生成。问题由类型化对象表达，并使用 clack 交互。差异计算可以作为编辑会话的内部实现，但不成为要求调用方组装的公共执行协议。
|
||||
|
||||
## 术语
|
||||
|
||||
| 名词 | 本文用词 | 含义 |
|
||||
|---|---|---|
|
||||
| Feature | 功能 | SDK 人工策划和管理的产品单元；一项功能可以包含多个功能选项，并贡献多个 Cordis 配置项、NPM 依赖、环境变量占位和独占文件 |
|
||||
| Feature option | 功能选项 | 一项功能内有限、可选择的实现或配置形状；根据功能规则可以固定、互斥或多选 |
|
||||
| Cordis plugin | Cordis 插件 | Cordis 加载的插件实现，通常由一个 NPM 包导出；它不是 `cordis.yml` 中的一项配置 |
|
||||
| Cordis config entry | Cordis 配置项 | `cordis.yml` 插件列表中的一项，通过 `id` 标识实例并通过 `name` 指向 Cordis 插件 |
|
||||
| Cordis plugin config | Cordis 插件配置 | Cordis 插件公开的配置对象或配置结构；其中由功能拥有并更新的单个字段称为“配置键” |
|
||||
| config key | 配置键 | Cordis 插件配置中的单个字段；功能只更新自己声明拥有的配置键，并保留未知配置键 |
|
||||
| npm dependency | NPM 依赖 | `package.json` 中的包关系；`dependencies`、`devDependencies` 等字段保持原样 |
|
||||
| Feature requirement | 功能依赖 | 功能或功能选项通过 `requires` 声明的关系 |
|
||||
|
||||
## Package 边界
|
||||
|
||||
| Package | 责任 | 不负责 |
|
||||
|---|---|---|
|
||||
| `@deepseek-ai/dsh-helper` | 编辑会话、功能配置、工程模板渲染、包管理适配和 prompt 交互适配 | 启动 Cordis 应用或决定 create/config 的终端流程 |
|
||||
| `@deepseek-ai/dsh-scripts` | `dsh-sdk start/dev/build/config`、进程生命周期、项目入口加载、config 流程和所属终端文案模板 | 直接解释功能定义或修改 YAML/JSON AST |
|
||||
| `@deepseek-ai/create-sdk` | `npm create @deepseek-ai/sdk` 的参数、问题顺序、首次工程创建、安装收尾和所属终端文案模板 | 成为生成工程的运行时 NPM 依赖或提供库 API |
|
||||
|
||||
`@deepseek-ai/create-sdk` 是仓库 `@deepseek-ai/dsh-*` 命名规则的唯一例外；npm scoped initializer 约定要求 `npm create @deepseek-ai/sdk` 对应这个 package 名。该例外是仓库架构事实，不增加第三个开发者产品入口。
|
||||
|
||||
三个 package 只导出相邻层实际使用的最小入口，不提供 `src/*` 深路径。scripts 的库入口与构建配置子路径服务生成代码和项目构建配置，但开发者产品合同仍由 `dsh-sdk` 命令承担。
|
||||
|
||||
## 工程聚合与编辑会话
|
||||
|
||||
`SdkProject.create(root, request)` 构造尚未写盘的新工程快照，`SdkProject.open(root)` 加载已有工程。open 只要求根 `package.json` 与 `cordis.yml` 可读，其余文件是按需存在的资源；两条路径返回同一种只读聚合，并通过显式 origin 区分来源。
|
||||
|
||||
`project.edit()` 克隆项目文档形成 working copy。install、configure、enable、disable 和 addPlugin 等领域命令只修改 working copy；命令完成后立即重新检查所属功能，最终 commit 再检查全部关系和文件。
|
||||
|
||||
```text
|
||||
validate feature requirements and resource ownership
|
||||
-> validate every affected document
|
||||
-> compute changed and removed paths
|
||||
-> compare existing files with the session's original text
|
||||
-> write through one commit boundary
|
||||
-> return a new SdkProject snapshot and ChangeSet
|
||||
```
|
||||
|
||||
校验失败或检测到会话外修改时不写盘。“一次 commit”只表示写入前零副作用和单一写入口。`ChangeSet` 只描述功能、插件和文件的最终变化，用于 Review & Apply 与 create 收尾。
|
||||
|
||||
## 功能与资源所有权
|
||||
|
||||
功能是一等行为对象。浅层基类实现 install、configure、enable、disable、required/requires 校验和共同状态识别；固定功能选项、互斥功能选项与可多选功能选项共享这些生命周期。只有资源贡献依赖项目上下文或需要自定义 round-trip 的功能才使用专用行为类，其余功能通过标准化数据声明真正不同的部分。
|
||||
|
||||
每项功能贡献带稳定 key 的 Cordis 配置项、NPM 依赖、环境变量占位和独占文件。注册表初始化时拒绝不同功能声明同一个资源 key；同一功能的不同功能选项可以共享资源，并由该功能根据最终选项集合处理。
|
||||
|
||||
Cordis 配置项是功能安装锚点。NPM 包名判断配置项所属的功能，配置项 ID 区分同一插件包的多个实例；只有 NPM 依赖而没有功能拥有的 Cordis 配置项时，该功能仍视为未安装。Cordis 配置项存在后，缺失 NPM 依赖、无法读取的 Cordis 插件配置或资源冲突会使功能进入不一致状态，config 命令显示诊断并拒绝猜测式修改。
|
||||
|
||||
同一功能选项只更新其声明拥有的配置键，保留未知键。替换功能选项会删除旧功能选项独占且仍可确认的资源；无法确认旧资源或发现独占文件被用户修改时，整个操作失败。
|
||||
|
||||
## 问题与 workflow
|
||||
|
||||
问题由 TypeScript `Question<T>` 对象表达，默认值、校验、适用条件和类型留在同一个对象中。`PromptPort` 是领域层与终端库之间的唯一接口，helper 提供一份薄 `ClackPromptPort`；create 和 config 注入各自的命令行输入输出流，并在各自流程中决定取消、返回和收尾语义。
|
||||
|
||||
create 的有状态问题顺序留在一个向导中，config 的最终状态选择留在一个流程中。两者通过同一个功能配置器收集功能选项与专用输入，因此增加一项普通功能、功能选项或参数不要求同时修改两个入口。
|
||||
|
||||
## 项目文档与模板
|
||||
|
||||
只有需要读取或修改的结构化文件拥有具体文档对象，包括 `package.json`、`cordis.yml`、`.env`、`.env.example`、根 `tsconfig.json` 和 pnpm workspace 文件。文档对象拥有解析、克隆、校验和序列化行为；具体类与模块分别使用 `*File` 和 `*-file.ts` 命名，业务层不直接操作 YAML/JSON AST，异常形状在所属文档边界 fail loud。
|
||||
|
||||
README、入口代码、构建配置、`.gitignore` 和其他一次性文本产物使用与真实文件一一对应的完整模板。CLI usage、创建结果与恢复提示、安装与重试指导以及默认 persona 等完整产品文案也由所属 package 的本地模板提供。
|
||||
|
||||
helper 提供通用的数据类型化 `TextTemplate` 模板渲染器，调用 package 通过本地 asset URL 加载自己的模板。
|
||||
|
||||
模板使用 Handlebars strict mode 与 `noEscape`，不进行自定义处理。文件对象负责把类型化数据值编码成目标语言文本；如果不希望插值，则源码以 `\{{model}}` 等转义形式输出下游。
|
||||
|
||||
## 命令与运行边界
|
||||
|
||||
scripts 支持 `dsh-sdk start/dev/build/config`。start 动态加载模块 target 并调用其命名入口；dev 在同一路径前增加 TypeScript 与本地 workspace 源码解析；build 调用工程安装的 tsdown；config 打开一个编辑会话并在 Review & Apply 后提交。typecheck 由生成工程直接执行 `tsc -b`。
|
||||
|
||||
HMR 作为显式 Cordis 配置项由 dev 和 start 加载；它所需的 `node-addon-require-builtin` 由 scripts package 传递提供，不写入开发者工程的 `package.json`。
|
||||
|
||||
dev/start 会执行开发者入口，在开发者代码中处理命令行参数、cwd，由开发者自行传入 `--model=<name>` 与 `--resume=<session-id>` 启动标准流程。
|
||||
|
||||
## 仓库本地链接模式
|
||||
|
||||
create-sdk 保留隐藏的 `--link-workspace` 选项供 Harness 仓库开发和 e2e 使用。该选项可以被解析，但不出现在 help、公开 flag 清单或普通用户文档中，也不接收仓库路径参数；仓库根从正在执行的 create-sdk 模块位置向上确定。
|
||||
|
||||
链接模式保持普通工程的文件形状。`@deepseek-ai/*` 指向 `packages/`，Cordis 相关 NPM 依赖指向 `vendor/`，共享底层 package 锚定到仓库实际使用的同一物理拷贝，避免 Cordis 类型合并产生多个模块类型定义。npm 使用 `file:`，pnpm 使用 `link:` 并关闭自动 peer 安装，Yarn 使用 `portal:` 与 resolutions；仓库 package 需要先构建。
|
||||
|
||||
## 后续工作
|
||||
|
||||
- **可替换的 required 主干角色。** 当前 `spine` 以一个固定功能选项拥有整组实现，包含 SystemPrompt、LLMService 等。无法让开发者对其进行替换和切换，只能手工修改 Cordis 配置项。
|
||||
- **Service contract 与 package 声明。** 替换特定内建服务时，Cordis 插件目前无法通过 `provides` 元数据声明其提供的服务，因此 SDK 无法在开发阶段辅助配置，也无法在运行时检查兼容性。后续需要设计相应协议。
|
||||
- **功能参数描述。** 当前功能的专用输入必须手工声明；SDK 无法从任意 Cordis 插件配置或 NPM package.json 信息中自动推导可交互参数。后续可以定义有限的声明式参数元数据，但不把任意 Cordis 插件配置转换成通用表单。
|
||||
- **SDK 应用级配置。** 当前项目资源模型只描述 Cordis 配置项及单个 Cordis 插件拥有的配置键，因此所有受 SDK 管理的配置都必须归属某个插件。跨插件或面向整个 SDK 应用的设置没有独立持久化位置；后续需要定义应用级配置文档及其所有权、读取和修改边界。
|
||||
|
||||
## 曾考虑的替代方案
|
||||
|
||||
**保留静态 Catalog 与中心 engine。** 该方案改动最小，但功能参数、round-trip、独占文件和 create/config 复用都会继续进入同一个协调中心；拆文件只能缩短单文件，不能收拢职责。
|
||||
|
||||
**使用 `wizard.json` 与通用 Questionnaire。** 静态表单无法直接表达功能依赖、选项切换、已有值回填和项目资源变化；类型、gate 和动态 option 最终仍要通过字符串 registry 与过程式 `run()` 连接，形成新的内部 DSL。
|
||||
|
||||
**公开本地链接 flag。** 该模式依赖 Harness monorepo 布局和未发布 package，只服务仓库开发；公开后会形成无法对外兑现的项目创建合同，因此保持隐藏。
|
||||
|
||||
## 验收标准
|
||||
|
||||
- create 与 config 只通过 `SdkProject` 和 `ProjectEditSession` 修改工程，写入前的任何业务、文件或并发校验失败都不产生磁盘变化
|
||||
- 新增普通功能、功能选项或参数只扩展类型化 spec 或所属行为对象，create/config 流程不增加中央 switch
|
||||
- 功能模型、NPM 依赖与其他资源配置、不一致检测由 helper 统一实现
|
||||
- 结构化文件通过 `*File` 文档对象修改；一次性文件和完整产品文案通过所属 package 的 Handlebars 模板生成，业务决策不进入模板 DSL
|
||||
- `dsh-sdk start/dev/build/config` 是运行产品面，typecheck 直接使用 `tsc -b`，HMR 不通过命令隐式注入，`node-addon-require-builtin` 只由 scripts package 传递提供
|
||||
- `--link-workspace` 只作为隐藏的仓库开发选项存在，并对 npm、pnpm 和 Yarn 保持单一模块身份
|
||||
|
||||
## 风险
|
||||
|
||||
- 行为对象与类型化 spec 并存会形成两种扩展形状；专用类必须只用于确实依赖项目上下文或自定义的功能，否则会重新产生无意义的类型层次
|
||||
- 乐观并发检查与写前校验不能解决写入中途的 I/O 故障，调用方仍需向开发者报告可能的部分提交
|
||||
- 隐藏链接模式依赖仓库目录与 package manager 链接语义，仓库布局或工具行为变化时必须与实现一起更新
|
||||
- Cordis loader 从自身模块路径加载 `node-addon-require-builtin`；npm、pnpm 或 Yarn 的 NPM 依赖布局变化时，scripts package 必须继续满足该可选对等依赖（optional peer dependency）
|
||||
- Handlebars 的 `noEscape` 把目标语言编码责任交给 typed model 构造方；新增模板字段时必须在 owner 处完成正确转义，下游 Handlebars 占位符必须在模板源码中显式转义
|
||||
@@ -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
|
||||
2026-07-14-sdk-developer-projects.md: 0b5fe876f92153e1ccf5bd8fe383464f5087f4b1
|
||||
2026-07-14-sdk-developer-projects.zh.md: ec08f323acba1b9dc049182937fda34bfb50d4ee
|
||||
167
docs/rfc/proposed/feature/2026-07-14-sdk-developer-projects.md
Normal file
167
docs/rfc/proposed/feature/2026-07-14-sdk-developer-projects.md
Normal file
@@ -0,0 +1,167 @@
|
||||
# RFC: Developer-owned SDK projects
|
||||
|
||||
Status: proposed
|
||||
|
||||
English | [中文](2026-07-14-sdk-developer-projects.zh.md)
|
||||
|
||||
## Problem
|
||||
|
||||
DeepSeek Harness composes features through Cordis plugins, but building a runnable project from an empty directory still requires a developer to understand npm dependencies, the `cordis.yml` plugin set, environment variables, TypeScript builds, local-plugin workspaces, and runtime entrypoints together. These manual steps constrain one another: omitting any one can produce a project that installs but cannot be developed, develops but cannot be built, or builds but cannot start.
|
||||
|
||||
A one-shot generator reduces only the initial creation cost. If the generated result is hidden inside a preset or an uneditable CLI, advanced developers cannot reshape the plugin tree, change Cordis plugin config, or add project-specific behavior. If a generated project immediately leaves tool management altogether, developers must again maintain consistency across all npm dependencies and Cordis plugin config themselves.
|
||||
|
||||
Initial creation and later configuration address the same builtin feature set. When those workflows maintain separate feature lists, feature options, and npm dependencies, new Cordis plugins, npm packages, and Cordis plugin config changes make them diverge. Projects also need an ordinary local-plugin development path that participates in development, build, and start flows.
|
||||
|
||||
## Proposal
|
||||
|
||||
The SDK creates an ordinary, explicit TypeScript/Cordis project owned by its developer. `cordis.yml` is the only runtime plugin tree; development and production read the same file. The generated `package.json`, `cordis.yml`, TypeScript entrypoint, build configuration, and `plugins/*` remain directly editable instead of being hidden behind a preset.
|
||||
|
||||
The only developer product entrypoints are `npm create @deepseek-ai/sdk` and the `dsh-sdk` commands. The initializer performs initial creation, `dsh-sdk config` manages SDK-recognized builtin features afterward, and `dsh-sdk dev`, `dsh-sdk build`, and `dsh-sdk start` own development, build, and startup; this phase provides no `dsh-sdk create`. Create and config consume one manually authored feature definition, so each feature has one source for its feature options, npm dependencies, Cordis config entries, related files, and inspection rules. The [SDK project editing architecture](../architecture/2026-07-15-sdk-project-editing-architecture.md) defines terms such as feature and feature option.
|
||||
|
||||
The SDK offers interaction for feature selection and finite feature options only; it does not turn arbitrary Cordis plugin config into a generic form. A feature collects the small number of dedicated inputs required by its feature options. All other Cordis plugin config remains in `cordis.yml`, with comments documenting common edits, for direct developer control.
|
||||
|
||||
## Developer workflow
|
||||
|
||||
Initial creation collects information in an order where earlier answers determine later questions: target directory and package identity, model provider and credentials, run interface, builtin features and feature options, an optional local plugin, package manager, and whether to install npm dependencies and build. Command-line arguments suppress questions they already answer. Create and config require an interactive TTY in this phase, and cancelling creation writes nothing to the target directory.
|
||||
|
||||
```sh
|
||||
npm create @deepseek-ai/sdk my-agent
|
||||
cd my-agent
|
||||
npm exec dsh-sdk dev index.ts
|
||||
npm exec dsh-sdk config
|
||||
npm exec dsh-sdk build
|
||||
npm exec dsh-sdk start index.js
|
||||
```
|
||||
|
||||
Create rejects every target path that already exists. After committing the project files, the CLI asks whether to install npm dependencies and build. An install or build failure preserves the generated project and prints commands that can retry the failed work.
|
||||
|
||||
Create also offers one `none / plugin / tool` choice. `plugin` creates a fixed `plugins/plugin` Cordis plugin, while `tool` creates a fixed `plugins/tool` model-facing tool; one project creation includes at most one local plugin. The operation updates the workspace, root npm dependency, TypeScript reference, build configuration, and `cordis.yml` together, and any pre-write validation failure leaves the project absent.
|
||||
|
||||
## Features supported during creation
|
||||
|
||||
The table is the developer-visible support set for this phase. A `required` feature is always present but may still offer finite feature options; a `default` feature is preselected in the feature tree; an `optional` feature is selected explicitly. The table describes the product support set, while the runtime registry remains the implementation source of truth.
|
||||
|
||||
| Feature | Create state | Feature options | Constraints and relationships |
|
||||
|---|---|---|---|
|
||||
| `provider` | required | `deepseek` (default) / `custom` | DeepSeek collects an API key; custom also collects a base URL, and a CLI option may override the model name |
|
||||
| `app` | required | `stdio` (default) / `acp` / `embed` | Selects the run interface |
|
||||
| `spine` | required | `default` | Timer, the LLM seam, session storage, system prompt, the tool registry, the agent registry, and the agent loop |
|
||||
| `bash` | required | `local` (default) / `sandbox` | The two feature options are exclusive and independent of the run interface, and both install the model-facing bash tool; sandbox installs the local sandbox provider and sandboxed bash backend |
|
||||
| `persistence` | required | `jsonl` (default) / `sqlite` | Every project selects exactly one persistence backend |
|
||||
| `hmr` | default | `default` | Loads `@cordisjs/plugin-hmr`; dev and start both enable it with the plugin defaults |
|
||||
| `fs` | default | `local` | Installs the local filesystem, policy, and model-facing tools; the process sandbox does not confine in-process fs tools |
|
||||
| `todo` | default | `default` | Provides the `todo_write` tool |
|
||||
| `skill` | default | `default` | Installs the skill registry, the local skill provider, and the model-facing skill tool |
|
||||
| `web` | optional | `deepseek` (default) / `exa` / `perplexity` / `fetch-only` | Search feature options are exclusive; Exa and Perplexity collect their API keys; timeout policy is recommended |
|
||||
| `subagent` | optional | `spawn` (default) / `fork`, multiple | This phase provides only in-process backends |
|
||||
| `workflow` | optional | `workerthread` | Requires the subagent `spawn` feature option |
|
||||
| `compact` | optional | `basic` | Uses SDK-provided context-compaction parameters |
|
||||
| `hooks` | optional | `claude` (default) / `codex`, multiple | Each feature option creates a separate editable configuration file |
|
||||
| `guard` | optional | `repeat-tool` | Provides repeated-tool-call reminders |
|
||||
| `timeout-policy` | optional | `default` | Applies a uniform policy to tools that declare timeout budgets |
|
||||
| `ask-user` | optional | `default` | Provides the `ask_user_question` tool; only `acp` and `stdio` can select it because those two feature options provide the injected user-interaction service |
|
||||
|
||||
Both `bash` feature options apply to ACP, stdio, and embed and are not selected by the run interface. The sandbox feature option writes no active config key and therefore keeps `dsh-bash-sandbox`'s `read-only` default. Generated `cordis.yml` includes a commented example that developers can change explicitly to `workspace-write`:
|
||||
|
||||
```yaml
|
||||
- id: bash
|
||||
name: '@deepseek-ai/dsh-bash-sandbox'
|
||||
# Uncomment to allow writes under the project workspace.
|
||||
# config:
|
||||
# mode: workspace-write
|
||||
# workspaceRoot: !!js process.cwd()
|
||||
```
|
||||
|
||||
Feature contributions reference only single-plugin npm packages and never bundle packages such as `agent-spine-demo`, `stdio-demo`, or `acp-demo`. Plugins outside the table are not managed by create in this phase; advanced developers may still compose them by editing the ordinary project files directly.
|
||||
|
||||
## Generated project
|
||||
|
||||
With default answers, an npm project uses the DeepSeek provider, the stdio interface, local bash, JSONL persistence, and the preselected hmr, fs, todo, and skill features. Its initial tree is:
|
||||
|
||||
```text
|
||||
my-agent/
|
||||
├── .env
|
||||
├── .env.example
|
||||
├── .gitignore
|
||||
├── README.md
|
||||
├── cordis.yml
|
||||
├── index.ts
|
||||
├── package.json
|
||||
├── tsconfig.base.json
|
||||
├── tsconfig.json
|
||||
└── tsdown.config.ts
|
||||
```
|
||||
|
||||
`.env.example` always exists, and the SDK keeps its placeholders aligned with the current feature set. A gitignored `.env` is also created when a secret is captured or the developer confirms an empty credential to fill later. The SDK only appends differently named variables that are not already present in `.env` and never updates or removes existing contents. Feature-option changes may remove obsolete `.env.example` placeholders, while old credentials remain in `.env` for the developer to manage. pnpm and Yarn projects add their required workspace files, but do not fork the runtime plugin tree or TypeScript entrypoint.
|
||||
|
||||
Generated `package.json` provides the following scripts. `dev`, `build`, `start`, and `config` invoke `dsh-sdk`, while `typecheck` invokes TypeScript directly:
|
||||
|
||||
| Script | Behavior |
|
||||
|---|---|
|
||||
| `dev` | Run `dsh-sdk dev index.ts`, registering development-time resolution for TypeScript and local workspace plugins |
|
||||
| `build` | Run `dsh-sdk build`, invoking the project's installed tsdown for the root entrypoint and `plugins/*` packages |
|
||||
| `typecheck` | Run `tsc -b` directly |
|
||||
| `start` | Run `dsh-sdk start index.js`, starting the built entrypoint without an implicit build |
|
||||
| `config` | Run `dsh-sdk config` to edit the current project's feature tree |
|
||||
|
||||
`dsh-sdk start` and `dsh-sdk dev` accept a module target and forward arguments after `--` unchanged to the project entrypoint. Generic argument parsing uses Node `parseArgs()` with zero schema: valued flags use `--key=value`, bare flags become `true`, and `--no-*` becomes `false`.
|
||||
|
||||
- Stdio projects pass the selected model through `--model=<name>` and create or resume an agent according to optional `--resume=<session-id>`;
|
||||
- ACP uses protocol `session/load`
|
||||
- Embed uses the model written into the generated code.
|
||||
|
||||
Each feature-owned Cordis config entry keeps its developer-editable Cordis plugin config and explanatory comments in `cordis.yml`. When `dsh-sdk config` changes other features, it preserves unknown fields, formatting on untouched nodes, and comments. HMR is an ordinary leaf config entry: when the feature is selected, dev and start load the same watcher, and the command does not change the plugin tree implicitly.
|
||||
|
||||
## Post-creation configuration
|
||||
|
||||
`dsh-sdk config` requires only readable root `package.json` and `cordis.yml` files in the current directory. It inspects standard features and their current feature options, expresses the final desired state through one feature tree, and shows feature changes and affected files before Review & Apply.
|
||||
|
||||
`dsh-sdk config` can install missing features, enable or disable installed features, and switch finite feature options. Required features cannot be removed. An npm dependency change runs the project package manager's install once after the file commit; installation failure does not roll back committed project files.
|
||||
|
||||
The SDK modifies only Cordis config entries, config keys, npm dependencies, `.env.example` placeholders, and owned files explicitly owned by a feature. Updating the same feature option preserves unknown config keys in its Cordis config entries. Handwritten and third-party plugins support enable and disable by stable ID only. When a known feature has been edited into an incomplete, ambiguous, or otherwise unreadable shape, `dsh-sdk config` displays diagnostics and refuses automatic changes until the developer repairs it manually.
|
||||
|
||||
One config session accumulates every change in an in-memory working copy. Before Apply, it validates feature relationships, resource conflicts, and document shapes, then compares each affected existing file with the text read when the session opened. Validation failure or an external edit causes zero writes. Once physical writes begin, the SDK does not provide cross-file transactional rollback.
|
||||
|
||||
## Maintenance model
|
||||
|
||||
The SDK curates its builtin support set instead of exposing npm packages automatically by npm dependency name or directory convention. One feature may compose several Cordis config entries, feature options may share resources, and a feature option may declare a feature requirement on another feature or a specific feature option. Adding an ordinary feature or feature option does not require changes to both create and config command workflows.
|
||||
|
||||
## Future work
|
||||
|
||||
- `dsh-sdk add [package-spec]` unifies local-plugin creation with external Cordis plugin installation: without a package or repository source it creates a local plugin/tool, while a supplied source adds the npm dependency and `cordis.yml` config entry; the source model leaves room for GitHub repositories and other extensions
|
||||
- Non-interactive create/config: both workflows require a TTY in this phase and provide no complete input contract for automation
|
||||
- More feature-specific inputs: this product surface exposes only finite feature options, secrets, and a few dedicated values in this phase rather than a generic parameter interface for Cordis plugin config
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
**An opaque preset or generator-owned project.** This shortens initial creation but hides the real plugin tree and build boundaries, prevents advanced developers from composing Cordis plugins directly, and makes project behavior depend on the CLI version rather than committed project files.
|
||||
|
||||
**A one-shot generator only.** Leaving all later maintenance manual redistributes feature requirements, feature-option switches, and multi-file updates. A config workflow over the shared registry retains continuing management for generated projects.
|
||||
|
||||
**Separate `cordis.yml` files for development and production.** Two plugin trees mean a successful development run does not demonstrate that production loads the same features. Dev adds only TypeScript and local-workspace resolution; runtime configuration remains singular.
|
||||
|
||||
**A generic form for arbitrary Cordis plugin config.** Cordis plugin config contains nested structures, expressions, and plugin-specific semantics. A generic form would become a second incomplete schema. The SDK manages finite feature options and dedicated secrets, while developers continue to edit complex config directly.
|
||||
|
||||
**A private local-plugin discovery protocol.** Ordinary package-manager workspaces, root npm dependencies, TypeScript references, and Cordis config entries already express the complete relationship. Another discovery protocol would create hidden state understood only by the SDK.
|
||||
|
||||
**A `dsh-sdk create` command for existing projects.** Create already provides one editable local-plugin skeleton, and later plugins can use ordinary workspace and Cordis mechanisms manually. A parallel command would add a second scaffolding product surface without adding composition functionality.
|
||||
|
||||
**Automatically expose every new Cordis plugin as a builtin.** An npm package cannot say how several plugins compose into one product feature, nor can it derive exclusivity, feature requirements, secrets, interface applicability, or security constraints. The support set requires human curation; automation is suitable only for checking whether candidates have been classified.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- `npm create @deepseek-ai/sdk` collects project identity, provider, interface, features, an optional local plugin, package manager, and installation choice in the documented order, and cancellation leaves the target path absent
|
||||
- A default npm project has the documented tree and `dev`, `build`, `typecheck`, `start`, and `config` scripts, with dev and start sharing one `cordis.yml`
|
||||
- Create offers the documented features and feature options; local and sandbox bash are exclusive with local as the default, the sandbox Cordis config entry retains the editable commented config example, and HMR is selected by default and loaded by both dev and start
|
||||
- Create's `plugin` or `tool` choice creates at most one fixed-name local plugin and atomically updates its files and root-project relationships; this phase provides no `dsh-sdk create`
|
||||
- `dsh-sdk config` reads the same support set from an existing project, installs, enables, disables, and switches supported feature options, preserves unknown config and comments, and refuses to modify inconsistent config
|
||||
- `.env.example` reflects variables required by the current features; `.env` only appends missing differently named variables and never updates or removes existing contents
|
||||
- npm, pnpm, and Yarn workspaces install, build, and start; local plugins resolve from source under dev and from built output under start
|
||||
|
||||
## Risks
|
||||
|
||||
- Developers can edit a builtin into a shape the registry cannot recognize; the SDK stops automating that feature instead of guessing and overwriting config
|
||||
- Pre-write validation and external-edit detection do not provide transactional rollback once multi-file writes begin; an I/O failure can leave a partial commit requiring manual repair
|
||||
- The sandbox feature option depends on an available local sandbox backend for the target platform; an unavailable backend must fail closed instead of falling back to unsandboxed execution
|
||||
- HMR retains its filesystem watcher and hot-reload behavior under production start; this is the result of an explicit plugin choice, not an implicit development-only service
|
||||
- The append-only `.env` policy retains credentials that are no longer used; the SDK does not decide when user-owned secret data is safe to delete
|
||||
@@ -0,0 +1,167 @@
|
||||
# RFC: 开发者拥有的 SDK 工程
|
||||
|
||||
Status: proposed
|
||||
|
||||
[English](2026-07-14-sdk-developer-projects.md) | 中文
|
||||
|
||||
## 问题
|
||||
|
||||
DeepSeek Harness 通过 Cordis 插件对功能进行组合，但从空目录开始搭建一个可运行工程仍要求开发者同时理解 NPM 依赖、`cordis.yml` 插件组、环境变量、TypeScript 构建、本地插件 workspace 和运行入口。手工步骤之间存在约束，漏掉任意一处都会得到能够安装却无法开发、能够开发却无法构建，或能够构建却无法启动的工程。
|
||||
|
||||
一次性生成器只能降低首次创建成本。若生成结果隐藏在 preset 或不可编辑的 CLI（命令行界面）内部，高级开发者无法调整插件树、修改 Cordis 插件配置或增加项目特有行为；若创建后的工程完全脱离工具管理，开发者又必须重新承担所有 NPM 依赖和 Cordis 插件配置的一致性工作。
|
||||
|
||||
初始创建和后续配置面对同一组内置功能。两条流程各自维护功能列表、功能选项和 NPM 依赖时，新增 Cordis 插件、NPM 包或调整配置会使二者逐渐分叉。工程还需要一条普通的本地插件开发路径，参与开发、构建和启动流程。
|
||||
|
||||
## 提案
|
||||
|
||||
SDK 创建一个普通、显式且归开发者所有的 TypeScript/Cordis 工程。`cordis.yml` 是唯一的运行时插件树；开发和生产读取同一份文件。工程中的 `package.json`、`cordis.yml`、TypeScript 入口、构建配置和 `plugins/*` 均可直接编辑，SDK 不把它们封装成不可见的 preset。
|
||||
|
||||
开发者产品入口只有 `npm create @deepseek-ai/sdk` 和 `dsh-sdk` 命令。前者负责首次创建，`dsh-sdk config` 在创建后管理 SDK 能识别的内置功能，`dsh-sdk dev`、`dsh-sdk build` 与 `dsh-sdk start` 负责开发、构建和启动；本期不提供 `dsh-sdk create`。create 与 config 使用同一份人工编写的功能定义，因此一项功能的功能选项、NPM 依赖、Cordis 配置项、相关文件和识别规则只有一个来源。功能、功能选项等名词由 [SDK 工程编辑架构](../architecture/2026-07-15-sdk-project-editing-architecture.md) 的术语表定义。
|
||||
|
||||
SDK 只为功能选择和有限功能选项提供交互，不尝试把任意 Cordis 插件配置变成通用表单。功能选项所需的少量专用输入由所属功能收集；其余 Cordis 插件配置留在 `cordis.yml` 中，并通过注释指明常用改法，由开发者直接修改。
|
||||
|
||||
## 开发者流程
|
||||
|
||||
首次创建按会影响后续问题集合的顺序收集信息：目标目录与 package 身份、模型提供方与凭据、运行接口、内置功能与功能选项、可选本地插件、包管理器，以及是否安装 NPM 依赖并构建。命令参数已提供的答案不重复询问；本期 create 和 config 都要求交互式 TTY，取消创建时不写入目标目录。
|
||||
|
||||
```sh
|
||||
npm create @deepseek-ai/sdk my-agent
|
||||
cd my-agent
|
||||
npm exec dsh-sdk dev index.ts
|
||||
npm exec dsh-sdk config
|
||||
npm exec dsh-sdk build
|
||||
npm exec dsh-sdk start index.js
|
||||
```
|
||||
|
||||
create 拒绝任何已经存在的目标路径。工程文件提交成功后，CLI 询问是否安装 NPM 依赖并构建；安装或构建失败时保留生成结果，并打印可以重新执行的命令。
|
||||
|
||||
create 还提供一次 `none / plugin / tool` 选择。`plugin` 固定生成 `plugins/plugin` 的 Cordis 插件，`tool` 固定生成 `plugins/tool` 的模型工具；一次创建至多包含一个本地插件。生成操作同时更新 workspace、根 NPM 依赖、TypeScript reference、构建配置和 `cordis.yml`，任何写入前校验失败都不创建工程。
|
||||
|
||||
## 创建时支持的功能
|
||||
|
||||
下表是本期 create 面向开发者展示的支持集。`required` 始终存在但仍可切换有限功能选项；`default` 在选择树中预选；`optional` 由开发者主动选择。表格说明产品支持集，运行时注册表是实现的事实源。
|
||||
|
||||
| 功能 | create 状态 | 功能选项 | 限制与关系 |
|
||||
|---|---|---|---|
|
||||
| `provider` | required | `deepseek`（默认）/ `custom` | DeepSeek 收集 API key；custom 另收集 base URL，模型名可由 CLI 参数覆盖 |
|
||||
| `app` | required | `stdio`（默认）/ `acp` / `embed` | 选择运行接口 |
|
||||
| `spine` | required | `default` | timer、LLM seam、会话存储、系统提示词、工具注册表、agent 注册表，以及 agent loop |
|
||||
| `bash` | required | `local`（默认）/ `sandbox` | 两个功能选项互斥、与运行接口正交，且都安装面向模型的 bash 工具；sandbox 安装本地沙箱提供方和沙箱 bash 后端 |
|
||||
| `persistence` | required | `jsonl`（默认）/ `sqlite` | 每个工程恰好选择一个持久化后端 |
|
||||
| `hmr` | default | `default` | 加载 `@cordisjs/plugin-hmr`；dev 和 start 都启用，使用插件默认配置 |
|
||||
| `fs` | default | `local` | 安装本地文件系统、策略和模型工具；进程沙箱不约束进程内 fs 工具 |
|
||||
| `todo` | default | `default` | 提供 `todo_write` 工具 |
|
||||
| `skill` | default | `default` | 安装 skill（技能）注册表、本地 skill 提供方和面向模型的 skill 工具 |
|
||||
| `web` | optional | `deepseek`（默认）/ `exa` / `perplexity` / `fetch-only` | 搜索功能选项互斥；Exa/Perplexity 收集各自 API key；建议同时启用 timeout policy |
|
||||
| `subagent` | optional | `spawn`（默认）/ `fork`，可多选 | 本期只提供进程内后端 |
|
||||
| `workflow` | optional | `workerthread` | 要求 subagent 的 `spawn` 功能选项 |
|
||||
| `compact` | optional | `basic` | 使用 SDK 提供的上下文压缩参数 |
|
||||
| `hooks` | optional | `claude`（默认）/ `codex`，可多选 | 各功能选项生成独立的可编辑配置文件 |
|
||||
| `guard` | optional | `repeat-tool` | 提供重复工具调用提醒 |
|
||||
| `timeout-policy` | optional | `default` | 对声明超时预算的工具执行统一策略 |
|
||||
| `ask-user` | optional | `default` | 提供 `ask_user_question` 工具；注入的 user-interaction 服务由 acp/stdio 两个功能选项提供，因此仅这两个接口可选 |
|
||||
|
||||
`bash` 的两个功能选项都适用于 ACP、stdio 和 embed，不由运行接口决定。sandbox 功能选项不写任何生效的配置键，因而沿用 `dsh-bash-sandbox` 的 `read-only` 默认值；生成的 `cordis.yml` 保留注释示例，开发者可以显式改为 `workspace-write`：
|
||||
|
||||
```yaml
|
||||
- id: bash
|
||||
name: '@deepseek-ai/dsh-bash-sandbox'
|
||||
# Uncomment to allow writes under the project workspace.
|
||||
# config:
|
||||
# mode: workspace-write
|
||||
# workspaceRoot: !!js process.cwd()
|
||||
```
|
||||
|
||||
功能贡献只引用单插件 NPM 包，绝不引用 `agent-spine-demo`、`stdio-demo`、`acp-demo` 这类组合 NPM 包。表格之外的插件不由本期 create 管理；开发者仍可直接编辑普通工程文件进行高级组合。
|
||||
|
||||
## 生成工程
|
||||
|
||||
使用默认答案创建 npm 工程时，provider 为 DeepSeek，运行接口为 stdio，bash 为 local，持久化为 JSONL，hmr、fs、todo 与 skill 处于选中状态。初始目录树为：
|
||||
|
||||
```text
|
||||
my-agent/
|
||||
├── .env
|
||||
├── .env.example
|
||||
├── .gitignore
|
||||
├── README.md
|
||||
├── cordis.yml
|
||||
├── index.ts
|
||||
├── package.json
|
||||
├── tsconfig.base.json
|
||||
├── tsconfig.json
|
||||
└── tsdown.config.ts
|
||||
```
|
||||
|
||||
`.env.example` 始终存在，并由 SDK 根据当前功能维护占位。收集到 secret 或开发者确认稍后填写空凭据时，同时生成 gitignored `.env`。SDK 只向 `.env` 追加尚不存在的不同名变量，绝不覆盖或删除已有内容；切换功能选项可以清理 `.env.example` 中不再需要的占位，但旧凭据仍留在 `.env` 中供开发者自行处理。pnpm 和 Yarn 工程增加各自所需的 workspace 配置文件，但运行时插件树和 TypeScript 入口不分叉。
|
||||
|
||||
生成的 `package.json` 提供以下 scripts；其中 `dev`、`build`、`start` 与 `config` 调用 `dsh-sdk`，`typecheck` 直接调用 TypeScript：
|
||||
|
||||
| script | 行为 |
|
||||
|---|---|
|
||||
| `dev` | 运行 `dsh-sdk dev index.ts`，为 TypeScript 和本地 workspace 插件注册开发期解析 |
|
||||
| `build` | 运行 `dsh-sdk build`，调用工程安装的 tsdown 构建根入口和 `plugins/*` package |
|
||||
| `typecheck` | 直接运行 `tsc -b` |
|
||||
| `start` | 运行 `dsh-sdk start index.js`，启动已构建入口且不隐式构建 |
|
||||
| `config` | 运行 `dsh-sdk config`，修改当前工程功能树 |
|
||||
|
||||
`dsh-sdk start` 与 `dsh-sdk dev` 可以接收模块 target，并把 `--` 后的参数原样转发给工程入口。通用参数解析使用 Node `parseArgs()` 的零 schema 模式：带值 flag 采用 `--key=value`，bare flag 转换为 `true`，`--no-*` 转换为 `false`。
|
||||
|
||||
- stdio 工程通过 `--model=<name>` 传入所选 model，并根据可选的 `--resume=<session-id>` 创建或恢复 agent；
|
||||
- acp 使用协议 `session/load`
|
||||
- embed 使用生成代码中的 model。
|
||||
|
||||
每个功能拥有的 Cordis 配置项在 `cordis.yml` 中保留自己的可编辑 Cordis 插件配置和说明注释；`dsh-sdk config` 修改其他功能时必须保留未知字段、未修改节点的格式和注释。HMR（热模块替换）是普通叶子配置项：选择该功能后，dev 和 start 加载同一个 watcher，命令不隐式改变插件树。
|
||||
|
||||
## 创建后的配置
|
||||
|
||||
`dsh-sdk config` 只要求当前目录具有可读的根 `package.json` 与 `cordis.yml`。它检查标准功能及其当前功能选项，以一棵功能树表达最终目标状态，并在 Review & Apply 前展示功能变化和受影响文件。
|
||||
|
||||
`dsh-sdk config` 可以安装缺失功能、启停已安装功能和切换有限功能选项。required 功能不能取消。改变 NPM 依赖后只运行一次项目包管理器安装；安装失败不回滚已经提交的工程文件。
|
||||
|
||||
SDK 只修改功能明确拥有的 Cordis 配置项、配置键、NPM 依赖、`.env.example` 占位和独占文件。同一功能选项的更新保留 Cordis 配置项中的未知配置键；手写或第三方插件只支持按稳定 ID 启停。已知功能被手改成不完整、歧义或无法读取的形状时，`dsh-sdk config` 显示诊断并拒绝自动修改，直到开发者手工修复。
|
||||
|
||||
一次 config 会话在内存工作区上累计全部修改。Apply 前完成功能关系、资源冲突和文件形状校验，并比较受影响文件与会话打开时的原文；校验失败或检测到外部修改时不写盘。实际写盘开始后不提供跨文件事务回滚。
|
||||
|
||||
## 维护模型
|
||||
|
||||
Builtin 支持集由 SDK 人工策划，不根据 NPM 依赖名称或目录约定自动暴露。一个功能可以组合多个 Cordis 配置项，功能选项可以共享资源，并声明对其他功能或特定功能选项的功能依赖；新增普通功能或功能选项不应要求同时修改 create 和 config 两个命令流程。
|
||||
|
||||
## 后续工作
|
||||
|
||||
- `dsh-sdk add [package-spec]`：统一本地插件创建与外部 Cordis 插件接入；未指定 package 或仓库来源时创建本地 plugin/tool，指定来源时增加 NPM 依赖和 `cordis.yml` 配置项，来源模型为 GitHub 仓库等扩展保留空间
|
||||
- 非交互 create/config：本期两个流程都要求 TTY，不提供供自动化调用的完整输入合同
|
||||
- 更多功能专用参数输入：本期产品只展示有限功能选项、secret 和少量专用值，不为 Cordis 插件配置提供通用参数界面
|
||||
|
||||
## 曾考虑的替代方案
|
||||
|
||||
**不可编辑的 preset 或生成器托管工程。** 该方案可以缩短初次创建路径，但会隐藏真实插件树和构建边界，使高级开发者无法直接组合 Cordis 插件，也让项目行为依赖 CLI 版本而不是检入的工程文件。
|
||||
|
||||
**只提供一次性生成器。** 创建后完全依赖手工维护，会让功能依赖、功能选项切换和多文件更新再次分散；共享 registry 的 config 流程为生成工程保留持续管理机制。
|
||||
|
||||
**为开发和生产维护两份 `cordis.yml`。** 两份插件树会使开发成功无法证明生产加载相同功能；dev 只增加 TypeScript 与本地 workspace 解析，运行配置保持唯一。
|
||||
|
||||
**为任意 Cordis 插件配置生成通用表单。** Cordis 插件配置包含嵌套结构、表达式和插件特有语义，通用表单会形成第二套不完整 schema。SDK 只管理有限功能选项和专用 secret，复杂配置继续由开发者直接编辑。
|
||||
|
||||
**使用私有协议发现本地插件。** 普通 package manager workspace、根 NPM 依赖、TypeScript references 和 Cordis 配置项已能表达完整关系；额外发现协议会创造只能由 SDK 理解的隐藏状态。
|
||||
|
||||
**在现有工程中提供 `dsh-sdk create`。** create 已能生成一种可编辑的本地插件骨架，后续插件可以沿用普通 workspace 和 Cordis 机制手工添加；再提供同构命令会增加第二条脚手架产品面，却不增加新的组合功能。
|
||||
|
||||
**把每个新 Cordis 插件自动暴露为 builtin。** package 无法说明多个插件如何组合成一项产品功能，也无法推导互斥关系、功能依赖、secret、接口适用性和安全限制；支持集需要人工策划，自动化只适合检查候选是否完成分类。
|
||||
|
||||
## 验收标准
|
||||
|
||||
- `npm create @deepseek-ai/sdk` 按本文顺序收集项目身份、provider、interface、功能、可选本地插件、包管理器和安装选择，并在取消时保持目标路径不存在
|
||||
- 默认 npm 工程具有本文目录树和 `dev`、`build`、`typecheck`、`start`、`config` scripts，且 dev/start 使用同一份 `cordis.yml`
|
||||
- create 展示本文功能及功能选项；`bash` 的 local/sandbox 二选一且默认 local，sandbox Cordis 配置项保留可编辑的注释配置示例；HMR 默认选中并同时由 dev/start 加载
|
||||
- create 的 `plugin` 或 `tool` 选择至多生成一个固定名称的本地插件，并原子更新插件文件与根工程关系；本期不提供 `dsh-sdk create`
|
||||
- `dsh-sdk config` 从现有工程读取同一支持集，能够安装、启停和切换支持的功能选项，保留未知配置与注释，并拒绝修改不一致配置
|
||||
- `.env.example` 反映当前功能所需变量；`.env` 只追加缺失的不同名变量，从不覆盖或清理已有内容
|
||||
- npm、pnpm 和 Yarn 生成的 workspace 能安装、构建和启动；本地插件在 dev 中使用源码，在 start 中使用构建产物
|
||||
|
||||
## 风险
|
||||
|
||||
- 开发者可以把 builtin 手改成 registry 无法识别的形状；SDK 选择停止自动化而不是猜测并覆盖配置
|
||||
- 多文件写入前的校验和外部修改检测不能提供写入阶段的事务回滚；I/O 中途失败可能留下需要人工修复的部分提交
|
||||
- sandbox 功能选项依赖目标平台存在可用的本地沙箱后端；后端不可用时必须 fail closed，不能退回无沙箱执行
|
||||
- HMR 在生产启动中也保持文件 watcher 和热重载行为；这是显式插件选择的结果，不是仅限开发环境的隐式服务
|
||||
- `.env` 的仅追加策略会保留已经不用的凭据，SDK 不判断这些用户数据何时可以安全删除
|
||||
Reference in New Issue
Block a user