@@ -1,4 +1,4 @@
# Agent Note: SDK 后续功 能
# Agent Note: SDK 后续能力
Status: proposed
@@ -8,13 +8,13 @@ Status: proposed
首个 SDK 版本通过[开发者工程 Agent Note ](2026-07-14-sdk-developer-projects.md ) 和 [SDK 工程编辑架构 ](../architecture/2026-07-15-sdk-project-editing-architecture.md )定义的共享模型创建和编辑开发者拥有的 Cordis 工程。create 和 config 工作流仅支持交互调用，接入外部 Cordis 插件需要手工修改依赖和配置，命令行遥测没有明确的所属边界，交互分支也缺少稳定的测试策略。
这些缺口彼此关联。create 和 config 已经共享问题、功能配置和 `ProjectEditSession` ；若另建自动化路径，就会复制领域逻辑。安装外部插件必须同时修改包管理器文件和 `cordis.yml` 。遥测需要观察 create、build 等不会启动 Cordis 的命令。交互测试需要覆盖 Harness 自身行为，同时避免把终端渲染固化成脆弱的产品契 约。
这些缺口彼此关联。create 和 config 已经共享问题、功能配置和 `ProjectEditSession` ；若另建自动化路径，就会复制领域逻辑。安装外部插件必须同时修改包管理器文件和 `cordis.yml` 。遥测需要观察 create、build 等不会启动 Cordis 的命令。交互测试需要覆盖 Harness 自身行为，同时避免把终端渲染固化成脆弱的产品约定 。
## 提案
SDK 扩展现有提示词与工程编辑边界，不另建平行工作流。非交互式 `PromptPort` 实现和结构化功能计划驱动 create 与 config； `dsh-sdk create <source>` 先把依赖解析交给工程的包管理器，再通过 `ProjectEditSession` 挂载解析所得的包；启动器侧遥测包住 `create-sdk` 和每个 `dsh-sdk` 命令；交互测试主要通过注入的提示词输入输出流完成。
| 功 能 | 产品入口 | 所属机制 | 必须达到的结果 |
| 能力 | 产品入口 | 所属机制 | 必须达到的结果 |
|---|---|---|---|
| Headless 工程创建 | `create-sdk --config <file>` 或 `--config-json <json>` ，可搭配 `--json` | `HeadlessPromptPort` 、结构化工程答案和完整功能计划 | 不阻塞等待终端；明确报告缺失的必答输入 |
| 外部 Cordis 插件安装 | `dsh-sdk create <source>` | 包管理器原生 `add` 加 `ProjectEditSession` | 依赖和 `cordis.yml` 配置项指向包管理器解析出的包 |
@@ -27,25 +27,25 @@ SDK 扩展现有提示词与工程编辑边界，不另建平行工作流。非
Headless create 通过 `--config-json` 接收内联 JSON 对象，或通过 `--config` 从文件读取。标量字段提供普通 create 答案，`features` 提供完整的已选功能、功能选项、secret（ ） ；
使用 `--json` 时， `done` 表示创建及要求执行的安装和构建 均已完成，`action-required` 指明一个尚未回答的必答问题，`error` 报告其他失败。面向人的进度信息和包管理器输出写入 stderr， `action-required` 后补充缺失值，再次运行命令。
使用 `--json` 时， `done` 表示创建及任何请求的设置 均已完成，`action-required` 指明一个尚未回答的必答问题，`error` 报告其他失败。面向人的进度信息和包管理器输出写入 stderr， `action-required` 后补充缺失值，再次运行命令。
Create 和 config 使用相同的功能计划形状。create 通过上述命令行输入公开该形状；
### Prompt 与工程编辑边界
### 提示词 与工程编辑边界
`PromptPort` 仍是 SDK 问题与交互实现之间的唯一边界。`ClackPromptPort` 负责终端交互。`HeadlessPromptPort` 使用问题契 约公开的默认值，否则通过未回答问题快速 失败；预填值通常会让流程根本不调用该 port。
`PromptPort` 仍是 SDK 问题与交互实现之间的唯一边界。`ClackPromptPort` 负责终端交互。`HeadlessPromptPort` 使用问题约定 公开的默认值，否则会因问题未回答而 失败；预填值通常会让流程根本不调用该 port。
两条路径使用相同的 `Question` 对象、`FeatureConfigurator` 、`SdkProject` 和 `ProjectEditSession` 。因此，
### A gent skill
### a gent skill（智能体技能）
仓库提供一份轻量 `SKILL.md` ，指导 agent skill（智能体技能） 构造结构化输入、请求 NDJSON、补充 `action-required` 指明的值并重试。该 skill 调用公开 CLI， ，
仓库提供一份轻量 `SKILL.md` ，指导 agent skill 构造结构化输入、请求 NDJSON、补充 `action-required` 指明的值并重试。该 skill 调用公开 CLI（命令行界面） ，不导入 SDK 内部 API，
## 外部 Cordis 插件安装
`dsh-sdk create <source>` 接受包管理器原生的 npm package specifier， `pkg@version` ，也接受 `github:owner/repo#ref` 等 GitHub package specifier。用户确认后， ， ， ， `ProjectEditSession` 把每个新增且已解析的包挂载进 `cordis.yml` 。
包管理器负责来源解析、版本或 commit 解析、`integrity` 数据、lockfile 更新和构建策略。SDK 不再 通过 giget 或 pacote 下载、解压第二份副本。外部插件是 `node_modules` 下的依赖；本地插件脚手架仍属于独立的工程创建问题。
包管理器负责来源解析、版本或 commit 解析、`integrity` 数据、lockfile 更新和构建策略。SDK 不会 通过 giget 或 pacote 下载、解压第二份副本。外部插件是 `node_modules` 下的依赖；本地插件脚手架仍属于独立的工程创建问题。
本提案只涉及开发者自有 SDK 工程的依赖。独立应用的仓库缓存、随应用捆绑 pnpm 的政策和显式的准备流程信任边界，均由[包管理器原生仓库缓存 ](../../implemented/architecture/2026-07-30-package-manager-native-repository-cache.md )负责。
@@ -78,43 +78,43 @@ Create 和 config 测试向现有工作流注入 `PromptPort` 和脚本化输入
## 曾考虑的替代方案
**
**另建 headless 创建引擎。** 该方案会复制问题、功能依赖、配置行为和工程编辑规则。复用提示词与编辑会话边界，可以保证工程语义只有一份实现。
**
**把规格文件作为主要自动化接口。** Agent 可以内联传入相同的类型化 JSON 对象，人和 CI 仍可选用文件。文件专用协议会增加持久化与清理工作，却不增加语义。
** ， ，
**使用 ** Skills CLI 只安装 Markdown skill， ，
**
**通过 giget 或 pacote 获取 GitHub 与 npm 来源。** 第二套获取层会复制包管理器的解析、完整性、lockfile 和生命周期策略。原生 package specifier 让这些决策留在所选包管理器中。
** ，
**把遥测实现成 Cordis 运行时插件。** Create 和 build 不一定启动 Cordis，
**
**从 git 元数据派生匿名标识符。** 仓库的 git remote 可能识别工程或组织。随机的用户级标识符能够支持聚合，同时不编码仓库身份。
**
**只采集聚合计数。** 仅聚合事件可以降低暴露，但无法回答开发者实际使用哪些插件、依赖和配置形状。本提案接受采集脱敏后的工程文本，并明确记录这项暴露。
（ ） ** ，
**把真实 PTY 和 transcript（ ） ** 原生 PTY 依赖与终端重绘序列会带来平台和渲染不稳定性，而且主要是在测试 clack。注入交互并断言生成文件，
## 验收标准
- Create 能依据完整结构化输入在没有 TTY 时运行；使用 `--json` 时 stdout 只输出 NDJSON； `action-required` 报告，且不写入部分工程。
- Create 和 config 通过共享的问题、功能配置和工程编辑代码路径解析相同的功能计划契 约。
- `dsh-sdk create <source>` 使用工程选定的包管理器，挂载该操作实际新增的依赖名；无法识别新增依赖时快速失败 。
- Create 和 config 通过共享的问题、功能配置和工程编辑代码路径解析相同的功能计划约定 。
- `dsh-sdk create <source>` 使用工程选定的包管理器，挂载该操作实际新增的依赖名；无法识别新增依赖时明确报错 。
- 初始化命令与每个 `dsh-sdk` 命令都进入同一条尽力而为的遥测收尾路径；明确禁用的配置项、`DO_NOT_TRACK` 或 CI 会阻止传输，遥测失败绝不改变命令结果。
- 遥测绝不读取 `.env` ；没有 `cordis.yml` 时不发送无关的 `package.json` 内容；两个符合条件的文本都经过脱敏；匿名标识符与 git 元数据无关。
- 交互测试通过注入交互覆盖 create 和 config 决策，并断言已提交的工程文件；真实 PTY 覆盖只作为窄范围冒烟层。
- Agent skill 说明公开的结构化输入与事件契 约，不依赖包的私有导出。
- Agent skill 说明公开的结构化输入与事件约定 ，不依赖包的私有导出。
## 风险
- 即使经过脱敏，完整的 `cordis.yml` 与 `package.json` 文本仍会向 endpoint 运营方暴露插件名、依赖名、URL、路径和配置值；
- 没有遥测配置项时默认上报可能让开发者意外；发布前 CLI 必须让关闭方法易于发现。
- 在 `ProjectEditSession` 挂载插件前，包管理器的 add 操作已经可能修改 `package.json` 、lockfile 和安装文件；后续挂载失败会 留下需要手工恢复的依赖改动。
- 在 `ProjectEditSession` 挂载插件前，包管理器的 add 操作已经可能修改 `package.json` 、lockfile 和安装文件；后续挂载失败可能 留下需要手工恢复的依赖改动。
- GitHub 依赖可能按包管理器策略执行 preparation 或 lifecycle script；
- 注入提示词交互的测试无法证明真实终端中的 raw mode、signal 或重绘行为；可选冒烟层只应覆盖这些残余契 约。
- 注入提示词交互的测试无法证明真实终端中的 raw mode、signal 或重绘行为；可选冒烟层只应覆盖这些残余约定 。
## 参考资料
- [Vercel Eve ](https://github.com/vercel/eve ) 与 [Vercel Labs Skills ](https://github.com/vercel-labs/skills ) 用于区分 headless 初始化命令与 skill 分发。
- [npm package specifications ](https://docs.npmjs.com/cli/v11/using-npm/package-spec )、[pnpm add ](https://pnpm.io/cli/add )和 [Yarn add ](https://yarnpkg.com/cli/add )说明包管理器原生来源。
- [`DO_NOT_TRACK` ](https://donottrack.sh/ )定义环境级关闭约定。
- [npm package specifications ](https://docs.npmjs.com/cli/v11/using-npm/package-spec )、[pnpm add ](https://pnpm.io/cli/add ) 和 [Yarn add ](https://yarnpkg.com/cli/add )说明包管理器原生来源。
- [`DO_NOT_TRACK` ](https://donottrack.sh/ ) 定义环境级关闭约定。
- [Clack ](https://github.com/bombshell-dev/clack ) 和 [Vitest snapshots ](https://vitest.dev/guide/snapshot ) 说明注入提示词交互与生成文件断言。
xjt