补充DirectProject Skill提及输入规范

更新聊天输入主规范并增加 Skill 提及边界新增 Skill 提及里程碑与小切片实施计划
2026-09-15 16:46:40 +08:00
parent 17716347e2
commit 23819d699c
3 changed files with 74 additions and 2 deletions
@@ -0,0 +1,27 @@
+# 【实施计划】DirectProject Skill 提及输入提示
+
+| 字段 | 值 |
+| --- | --- |
+| Milestone | `docs/project-memory/plans/【里程碑】DirectProject Skill提及输入提示-2026-09-15.md` |
+| Status | in-progress |
+| Owner | Codex |
+
+## 代码边界
+
+- 前端：`features/project-workspace/ResourceReferenceInput.tsx`、`ResourceReferenceNode.tsx`、`resourceReferences.ts`、生成绑定及聊天入口透传。
+- Rust：`agent/direct_codex_user_item/model.rs`、`validation.rs`、`wire.rs`、`codex_app_server/mod.rs` 与对应测试。
+- 文档：父规范与本里程碑/实施计划。
+
+## 小切片顺序
+
+1. 先扩展前端 Skill catalog/节点/草稿 content，保持素材行为不变并补前端测试。
+2. 扩展 canonical Rust part 与 ts-rs 绑定，补序列化和失败校验测试。
+3. 接通 Codex wire `type: skill` 转换和受控路径解析，补历史/重放测试。
+4. 完成入口透传、定向验证和文档证据；每个切片单独中文提交。
+
+## 验证与回滚
+
+- `npm --prefix apps/ai-game-creator-shell run typecheck`
+- 相关 Vitest 与 `cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml direct_codex`
+- `npm run check:encoding`、`npm run check:doc-index`、`git diff --check`
+- 每个切片只改计划列出的文件；若 Codex wire 协议或 Skill catalog 来源不确定，停在该切片并先更新规范。
@@ -0,0 +1,43 @@
+# 【里程碑】DirectProject Skill 提及输入提示
+
+| 字段 | 值 |
+| --- | --- |
+| Version | 1.0 |
+| Status | proposed |
+| Date | 2026-09-15 |
+| Parent Spec | `docs/【功能说明】AGC聊天素材引用-2026-09-08.md` |
+
+## 目标
+
+在现有 Lexical `ResourceReferenceInput` 中增加 Codex 风格 `$skill-name` 提及。用户选择 Skill 后，编辑器保留与文本相对顺序一致的原子节点；DirectProject canonical user item 保存稳定 Skill 名称，Rust 只允许当前已启用且 app-server 已发现的 Skill，并在 `turn/start` 转换为 Codex 原生 `type: "skill"` 输入项。
+
+## 范围
+
+- Skill 候选数据从当前 DirectProject 的已启用 Skill catalog 派生。
+- `$` typeahead 菜单、键盘选择、鼠标选择、Esc/Enter 交互与现有 `@` 菜单一致。
+- Skill inline 节点和 `content[]` 顺序恢复。
+- canonical `agc_skill_reference` part 的 ts-rs 类型、Rust 校验、历史写入与 Codex wire 转换。
+- 现有素材、运行区域、assistant、附件和工具 activity 行为保持不变。
+
+## 不在范围内
+
+- Skill 导入、启用、禁用、重命名和 app-server `skills/list` 生命周期改造。
+- 普通自然语言自动分类 Skill；只支持显式 `$skill-name` 选择。
+- Skill 正文预加载、Skill 内容编辑或新的权限/工具能力。
+- SpacetimeDB、HTTP API 和 assistant item 协议变更。
+
+## 验收标准
+
+- [ ] 输入 `$` 可显示并过滤可用 Skill，候选项显示名称和描述。
+- [ ] 选择 Skill 后插入原子 `$name` chip，文本与素材/运行区域的相对顺序保持不变。
+- [ ] canonical user item 只保存 Skill 稳定名称，不保存正文、凭据或宿主私密路径。
+- [ ] Rust 拒绝未知、禁用、未发现或名称非法的 Skill；失败时不写历史、不启动回合。
+- [ ] 合法 Skill 在 Codex wire input 中生成 `type: "skill"`、`name`、受控 `path`，顺序与 canonical content 一致。
+- [ ] 无 Skill 的旧消息、素材引用和标准 `response_item` 读取行为不变。
+
+## 证据要求
+
+- 前端：Lexical 草稿顺序、候选过滤、chip 原子性与 `$`/`@` 共存测试。
+- Rust：模型序列化、Skill catalog 校验、wire 转换、失败关闭和历史重放测试。
+- 运行时：DirectProject app-server smoke（环境可用时）。
+- 门禁：相关 Vitest、AGC Rust 定向测试、`npm run check:encoding`、`npm run check:doc-index`、`git diff --check`。
@@ -2,7 +2,7 @@

 更新时间：2026-09-08

-AGC 聊天输入框支持以结构化引用标记当前项目已登记素材。输入 `@` 会按素材名称、资源 ID 和类型过滤候选项；也可以点击输入框右侧的 `@` 按钮打开素材选择面板。
+AGC 聊天输入框支持以结构化引用标记当前项目已登记素材，并提供 Codex 风格的 Skill 提及。输入 `@` 会按素材名称、资源 ID 和类型过滤候选项；输入 `$` 会按当前 DirectProject 可用 Skill 名称过滤候选项；也可以点击输入框右侧的 `@` 按钮打开素材选择面板。

 素材选择面板支持缩略图、名称或资源 ID 搜索、类型筛选和多选；面板顶部有两个页签：

@@ -11,7 +11,7 @@ AGC 聊天输入框支持以结构化引用标记当前项目已登记素材。

 两个页签各自持有独立的搜索与类型筛选状态，互不影响，也不与资源画布筛选联动。当前版本取 `ResourceReferenceInput` 的 `activeVersionId`；未传或传 `null` 时回退到 manifest `versions[]` 中最新的那个版本。版本不存在或该版本没有绑定素材时页签显示空态，不合成资源卡；绑定指向已删除资源（悬空绑定）时按资源 `id` 过滤掉。

-确认后素材以 `@素材名` 芯片插入编辑器，用户可以在芯片前后继续编辑自然语言，也可以单独删除芯片。芯片内部保存稳定 `resourceId`，展示名称只用于界面，不参与引用解析；资源改名后，编辑区已有芯片与候选列表都会按 `resourceId` 刷新成 manifest 的最新显示名，并同步回父级草稿。
+确认后素材以 `@素材名` 芯片插入编辑器，Skill 以 `$skill-name` 芯片插入编辑器；用户可以在芯片前后继续编辑自然语言，也可以单独删除芯片。素材芯片内部保存稳定 `resourceId`，展示名称只用于界面，不参与引用解析。Skill 芯片保存稳定 Skill 名称，发送时由 Rust 根据当前 DirectProject 已启用 Skill 清单解析为 Codex 原生 `type: "skill"` 输入项。资源改名后，编辑区已有芯片与候选列表都会按 `resourceId` 刷新成 manifest 的最新显示名，并同步回父级草稿。

 提交时前端把 Lexical 草稿直接编码为受限 Response API user `message` item：`input_text` 与 AGC 引用 part 按编辑顺序内联在同一个 `content[]` 中。资源引用只携带稳定 `resourceId`；运行画面引用携带区域语义摘要及关联资源 ID。Rust 是唯一 schema source（通过 `ts-rs` 生成 TypeScript 绑定），在发起回合前完成 item 白名单、字段边界、manifest 归属和路径安全校验；校验失败时本轮不持久化、不发送。通过校验的 canonical item 以 `response_item` envelope 写入项目历史，随后由 Rust 将 AGC part 临时转换为 Codex 可接受的 `input_text`，保持原始 content 顺序。已有标准 `response_item` 原样读取与复用；旧 legacy conversation 行不再提供 fallback。

@@ -19,6 +19,7 @@ AGC 聊天输入框支持以结构化引用标记当前项目已登记素材。

 - 三个聊天入口共用 `ResourceReferenceInput`；
 - 输入 `@` 触发候选，支持键盘选择和 Esc 关闭；
+- 输入 `$` 触发 Skill 候选，支持键盘选择和 Esc 关闭；Skill 候选只显示当前 DirectProject 已启用且已由 app-server 发现的 Skill；
 - `@` 按钮打开素材选择面板；
 - 支持搜索、类型筛选和多选；
 - 素材芯片可插入、编辑和删除；
@@ -30,3 +31,4 @@ AGC 聊天输入框支持以结构化引用标记当前项目已登记素材。
 - 素材选择面板的「当前版本素材 / 全部画布素材」两个页签与独立筛选、搜索状态；
 - 资源改名后引用芯片与候选列表的显示名自动刷新；
 - 切换 / 重开会话恢复草稿后光标落在文本末尾，引用按原 content 顺序恢复为 inline 芯片。
+- Skill 提及按原 content 顺序恢复为 inline 芯片；未知、禁用或未发现 Skill 在发送前失败关闭，不写入历史、不启动回合。