yce

# YCE Skill

## 快速调用（AI Agent 复制即用）

**推荐先 `cd` 到 YCE 仓根目录，再直接执行下面这些命令：**

```bash
# 1) auto：模糊需求 + 要找代码，优先用这个
node ./scripts/yce.js "帮我看看这个 provider 那块是在哪里处理的" \
  --mode auto \
  --history "User: 我在看 provider 逻辑\nAI: 相关代码分散在多个模块\nUser: 帮我看看这个 provider 那块是在哪里处理的" \
  --cwd "/absolute/path/to/project" \
  --xml-pretty

# 2) enhance：只做提示词增强
node ./scripts/yce.js "优化这个任务描述" \
  --mode enhance \
  --history "User: ...\nAI: ..." \
  --xml-pretty

# 3) search：问题已经很具体，只做代码定位
node ./scripts/yce.js "定位 provider 列表获取逻辑" \
  --mode search \
  --cwd "/absolute/path/to/project" \
  --xml-pretty

# 4) 手工直调仓内增强脚本（仅用于调试 enhance，本身不会返回 YCE XML）
node ./scripts/youwen.js enhance "优化这个任务描述" \
  --history "User: ...\nAI: ..." \
  --auto-confirm --auto-skills

# 5) 手工直调 yce-engine 引擎（仅用于调试 search，本身不会返回 YCE XML）
node ./vendor/yce-engine/yce-engine.mjs --project "/absolute/path/to/project" --query "定位 provider 列表获取逻辑"

# 5b) 校验 relay / YCE_API_KEY 是否可用
node ./vendor/yce-engine/yce-engine.mjs --check-key

# 6) 查看帮助（返回 XML 帮助载荷；强制 pretty；exit code 0）
node ./scripts/yce.js --help
```

**调用约束：**
- `auto` 模式最稳，适合“问题不够具体，但最终要落到代码位置”的场景。
- `search` 模式如果不传 `--cwd`，会默认用当前 shell 目录；调用前先确认自己已经在目标项目目录里。
- 进入增强链路时，优先传 `--history`；YCE 内部调用 `yw-enhance` 时会固定追加 `--auto-confirm --auto-skills`。
- 外层等待建议 `>= 120s`；仓内默认 `YCE_TIMEOUT_ENHANCE_MS=300000`、`YCE_TIMEOUT_SEARCH_MS=180000`。
- `--json-pretty` 只是 `--xml-pretty` 的旧别名，**永远不会让 YCE 输出 JSON**。
- `--help` 也返回 XML，但它是帮助载荷，不是实际增强 / 检索结果。
- 不要在 home 目录或超大目录里做检索。

## 调用判断（真实行为）

`./scripts/lib/orchestrator.js` 的 `resolveAction(mode, query)` 是按下面这个优先级执行的：

```text
mode=enhance                         → enhance
mode=search                          → search
命中“检索意图” + 命中“模糊标记”     → enhance_then_search
命中“检索意图” + 命中“增强意图”     → enhance_then_search
只命中“检索意图”                    → search
其他情况                            → enhance
```

**关键点：**
- 同一句话如果同时命中“检索意图 + 模糊标记”，会优先进入 `enhance_then_search`，不会落到纯 `search`。
- 同一句话如果同时命中“检索意图 + 增强意图”，也会优先进入 `enhance_then_search`。
- 只有显式 `--mode enhance` / `--mode search` 才能跳过上面的自动分流。

### 1. 检索意图关键词（会倾向进入 search）
- `搜索代码`
- `找文件`
- `定位实现`
- `在哪` / `哪里`
- `函数` / `类` / `接口` / `api`
- `组件` / `模块`
- `provider` / `route` / `handler`
- `实现` / `逻辑` / `代码` / `文件`
- `settings` / `模型列表`

### 2. 增强意图关键词（会倾向先增强）
- `优化提示词`
- `提示词增强`
- `增强`
- `改写`
- `整理需求`
- `润色`
- `补全上下文`
- `更好理解`
- `优化这个任务`
- `prompt`

### 3. 模糊标记（命中后更容易变成 enhance_then_search）
- `这个`
- `这里`
- `那块`
- `相关逻辑`
- `对应地方`
- `这块`
- `那个`
- `它`
- `帮我看看`

**怎么选：**
- 用户话很模糊，但明确是“找代码” → `auto`
- 用户只想把任务说清楚，不需要搜代码 → `enhance`
- 用户已经给出了明确技术目标，只差定位代码 → `search`

## 输出契约（必须按真实标签消费）

YCE 的 stdout 固定是 XML，不再输出 JSON。最重要的标签如下：

| 标签 / 属性 | 含义 | 怎么用 |
|------------|------|--------|
| `<success>` | 整体是否产出了可用结果 | 只要增强或检索任一侧产出可用结果，就会是 `true` |
| `<mode>` | 你传入的模式 | `auto / enhance / search` |
| `<resolved-action>` | 实际执行动作 | `enhance / search / enhance_then_search` |
| `<enhanced success="...">` | 增强结果块 | 读 `<prompt>`、`<recommended-skills>`、`<raw-stdout>` |
| `<enhanced><prompt>` | 给人 / agent 看的增强提示词 | 需要继续调别的 agent / 工具时优先用这个 |
| `<enhanced><recommended-skills><skill>` | yw-enhance 推荐技能列表 | 按需继续调 skill |
| `<search result-present="...">` | 检索结果块 | 读 `<query>` 和 `<result>` |
| `<search><query>` | 实际送给 yce 的检索词 | 这是排障时最该看的搜索输入 |
| `<search><result>` | yce 原始检索结果 | 代码定位主结果看这里 |
| `<errors><error code="..." source="...">` | 错误列表 | 即使 `<success>true</success>` 也要检查 |
| `<meta><dependency-paths>` | 解析后的依赖路径 | 排障先看这里是不是走到了对的脚本 / binary |

### AI Agent 处理顺序

1. 先看 `<success>`
2. 再看 `<resolved-action>`
3. 如果走了增强，优先取 `<enhanced><prompt>`
4. 如果走了检索，优先取 `<search><result>`
5. 不要只看 `<search success="true">`，还要看 `result-present="true"`
6. 始终检查 `<errors>`

### 常见返回特征

```xml
<?xml version="1.0" encoding="UTF-8"?>
<yce>
  <success>true</success>
  <mode>auto</mode>
  <resolved-action>enhance_then_search</resolved-action>
  <enhanced executed="true" success="true" used-history="true">
    <prompt><![CDATA[增强后的检索问题]]></prompt>
    <recommended-skills>
      <skill><![CDATA[yce]]></skill>
      <skill><![CDATA[OpenHarnesses]]></skill>
    </recommended-skills>
  </enhanced>
  <search executed="true" success="true" result-present="true" empty-result="false" exit-code="0">
    <query><![CDATA[送给 yce 的检索词]]></query>
    <result><![CDATA[Path: src/...]]></result>
  </search>
  <errors/>
</yce>
```

### 帮助载荷是特殊例外（仍然是 XML）

`--help` 走的是帮助 XML，而不是正常任务流。它有几个容易误判的点：
- `stdout` 仍然是 XML
- 输出会**强制 pretty-print**，不依赖你有没有传 `--xml-pretty`
- 进程 **exit code = 0**
- 但 payload 本身是帮助 / 非法参数结构，所以你会看到 `<success>false</success>`、`<mode/>`、`<resolved-action/>`，以及 `errors.code="INVALID_ARGS"`

**重要细节：**
- `<search empty-result="true">` 时，`success="true"` 不代表已经搜到结果，还是要看 `result-present="true"`。
- `<errors>` 里常见的 `EMPTY_RESULT` 不等于崩溃，它表示“命令跑完了，但没搜到结果”。
- 手工运行 `vendor/yce-engine/yce-engine.mjs` 时，得到的是 raw yce-engine 输出，不是 YCE XML。

## 参数说明

| 参数 | 必须 | 说明 |
|------|:---:|------|
| `<query>` | ✅ | 用户原始问题或检索问题 |
| `--mode <auto\|enhance\|search>` | 可选 | 默认读 `YCE_DEFAULT_MODE`，仓内默认是 `auto` |
| `--history <text>` | 建议 | 进入增强链路时强烈建议传；格式示例：`User: ...\nAI: ...\nUser: ...` |
| `--cwd <path>` | 强烈建议 | 不在目标项目目录执行时必须传；否则默认取当前 shell 目录 |
| `--timeout-enhance-ms <n>` | 可选 | 覆盖增强超时 |
| `--timeout-search-ms <n>` | 可选 | 覆盖检索超时 |
| `--no-search` | 可选 | **只会传给 yw-enhance，表示增强阶段不做外部搜索；不会阻止 YCE 后续跑 yce 检索** |
| `--raw-events` | 可选 | 仅在走增强链路时抓 yw-enhance 原始事件摘要，用于排障 |
| `--xml-pretty` | 可选 | 美化 XML 输出 |
| `--json-pretty` | 可选 | **旧参数别名，当前只等同于 `--xml-pretty`，不会输出 JSON** |
| `--help` | 可选 | 输出 XML 帮助载荷；强制 pretty-print；payload 为 `INVALID_ARGS` 结构；exit code 0 |

## 依赖路径与真实优先级

运行时配置由 `./scripts/lib/utils.js` 从 `.env + process.env` 合并得到。当前仓已经把 search / enhance 两条主链路都收敛到了 `./scripts/`：

### 当前目录内可直接引用的仓内资源

| 环境变量 | 默认值 | 作用 |
|---------|--------|------|
| `YCE_YOUWEN_SCRIPT` | `./scripts/youwen.js` | 仓内优问增强入口 |
| `YCE_ENGINE_SCRIPT` | `./vendor/yce-engine/yce-engine.mjs` | yce-engine 检索入口 |
| `YCE_ENGINE_MAX_RESULTS` | `10` | 检索返回的最大文件数 |
| `YCE_ENGINE_MAX_TURNS` | `3` | 检索 agent 的最大轮数 |
| `YCE_RELAY_URL` | `https://yce.aigy.de` | 检索 relay 地址 |
| `YCE_RELAY_TOKEN` | 空 | YCE 搜索密钥；请求 `/yce/lease-key` 时作为 `Authorization: Bearer <token>` 发送 |
| `YCE_API_KEY` | 空 | 不走 relay 时的直连 key |
| `YCE_LOCAL_FALLBACK` | 空 | 设为 `true` 时远端失败才启用本地 fast fallback |
| `YCE_DEFAULT_MODE` | `auto` | 默认模式 |
| `YCE_TIMEOUT_ENHANCE_MS` | `300000` | 默认增强超时 |
| `YCE_TIMEOUT_SEARCH_MS` | `180000` | 默认检索超时 |

**关键说明：**
- 当前仓里的 `./scripts/youwen.js` 就是默认增强入口，不再要求先装外部 `yw-enhance`
- `YCE_YOUWEN_SCRIPT` 默认写成 `./scripts/youwen.js`，只有在你明确要覆盖时才改成别的路径
- `YCE_RELAY_URL` 默认固定写入 `https://yce.aigy.de`；`YCE_RELAY_TOKEN` 必须填写 YCE 搜索密钥，不会再从 `YCE_YOUWEN_TOKEN` 自动复制
- 纯 `search` 只依赖仓内 yce-engine 引擎；`enhance` 与 `auto` 会额外走仓内 `./scripts/youwen.js`

### YCE 传给 yw-enhance 的固定参数与环境变量

YCE 调 `yw-enhance` 不是裸调用，而是固定这样拼：

```text
./scripts/youwen.js enhance <prompt> --auto-confirm --auto-skills [--history <text>] [--no-search]
```

其中增强脚本默认就是仓内 `YCE_YOUWEN_SCRIPT=./scripts/youwen.js`；下游仍然使用 `YOUWEN_*` 子进程环境变量。

同时，YCE 会把自己的配置映射成下面这些子进程环境变量：

| YCE 环境变量 | 传给 yw-enhance 的变量 |
|-------------|------------------------|
| `YCE_YOUWEN_API_URL` | `YOUWEN_API_URL` |
| `YCE_YOUWEN_ENHANCE_MODE` | `YOUWEN_ENHANCE_MODE` |
| `YCE_YOUWEN_ENABLE_SEARCH` | `YOUWEN_ENABLE_SEARCH` |
| `YCE_YOUWEN_TOKEN` | `YOUWEN_TOKEN` |
| `YCE_YOUWEN_MGREP_API_KEY` | `YOUWEN_MGREP_API_KEY` |

### 检索链路真实逻辑

`search` / `enhance_then_search` 统一调用仓内 yce-engine 引擎：

```text
config.yceEngineScript（默认 ./vendor/yce-engine/yce-engine.mjs）
  → node 子进程执行 yce-engine.mjs --project <cwd> --query <q>
  → YCE semantic agent 在本地循环执行 rg/readfile/tree 收集上下文
  → 返回文件路径 + 行号范围 + 建议 grep 关键词
  → 若 yce-engine 返回 resource_exhausted / 上游错误 / 空结果，且 `YCE_LOCAL_FALLBACK=true`，才启用 local fast fallback
```

**关键细节：**
- 检索 key 只来自 relay 租约或 `YCE_API_KEY`。
- local fast fallback 仅在 `YCE_LOCAL_FALLBACK=true` 时启用，纯本机 rg/heuristic，不依赖任何桌面 IDE key。
- fallback 会跳过 `.git`、`node_modules`、`dist`、`build`、`coverage`、`vendor`、真实 `.env` 等噪声/敏感路径。
- 退出码 0 且输出含 `Found 0 relevant files` 时映射为 `EMPTY_RESULT`（命令成功但无结果）。
- 若 relay 租 key 失败，返回 `AUTH_ERROR`（优先检查 `YCE_RELAY_URL/YCE_RELAY_TOKEN` 或 `YCE_API_KEY`）。
- 引擎在本地循环执行 rg/readfile/tree 收集上下文；远端只做推理，**不上传代码、不建服务端索引**。
- 默认配置会写入 `YCE_RELAY_URL=https://yce.aigy.de`；`YCE_RELAY_TOKEN` 是独立的 YCE 搜索密钥，不能和 `YCE_YOUWEN_TOKEN` 混用。
- 排障时先看 `<meta><dependency-paths>` 里的 `yce-engine-script` 路径是否正确。

### 当前仓库已实际内置的检索资源

`vendor/yce-engine/` 里实际存在的是：
- `vendor/yce-engine/yce-engine.mjs`（CLI 入口）
- `vendor/yce-engine/lib/*.mjs`（核心逻辑：协议、relay 鉴权、本地命令执行）
- `vendor/yce-engine/node_modules/`（自带 `@vscode/ripgrep` / `tree-node-cli`，无需系统装 rg）

**这意味着：**
- 配好 relay 或 `YCE_API_KEY` 即可使用 YCE 检索链路，跨平台一致（rg 随引擎自带）。
- 不再依赖旧二进制或远程上传索引。
- 若设置 `YCE_LOCAL_FALLBACK=true`，远端失败时仍可用本机 heuristic 保持基础定位能力。

## 常见失败规避点

### 1. 当前目录不对，结果搜偏了
- **症状**：返回空结果，或者搜出来完全不是目标项目的内容
- **原因**：没传 `--cwd`，YCE 默认拿当前 shell 目录当项目目录
- **处理**：显式传 `--cwd "/absolute/path/to/project"`

### 2. 外层超时太短
- **症状**：`errors[].code === "TIMEOUT"`
- **原因**：增强链路本来就慢，外层又用了短 timeout 轮询
- **处理**：外层一次阻塞等待，建议 `>= 120s`

### 3. 误以为 `--no-search` 会跳过 yce 检索
- **症状**：明明加了 `--no-search`，还是执行了 search
- **原因**：这个参数只传给 yw-enhance，用来关闭增强阶段的外部搜索
- **处理**：如果你真的只想增强，不要用 `auto`，直接 `--mode enhance`

### 4. 只看 `search.success`，误判为空结果也是成功
- **症状**：agent 把“没搜到结果”当成“已经定位成功”
- **原因**：空结果场景里 `search.success` 和整体 `success` 不是一回事
- **处理**：同时检查 `search.result_present` 和 `errors[]`

### 5. `yw-enhance` 输出里没有 `<enhanced>`
- **症状**：`errors[].code === "PARSE_ERROR"`
- **原因**：底层 skill 输出格式变了，或者 stdout 被别的内容污染了
- **处理**：加 `--raw-events` 排障，并先单独验证 `YCE_YOUWEN_SCRIPT`

### 5.1 `YCE_YOUWEN_SCRIPT` 仍指到旧的外部 skill
- **症状**：`meta.dependency_paths.yw_enhance_script` 仍然指向 `~/.agents/skills/yw-enhance/...`
- **原因**：旧 `.env` / 旧安装脚本留下了外部路径，没切到仓内 `./scripts/youwen.js`
- **处理**：优先把 `.env` 改回 `YCE_YOUWEN_SCRIPT=./scripts/youwen.js`，再重新执行 `install.sh --setup` / `install.ps1 -Setup`

### 6. yce-engine 依赖缺失
- **症状**：`errors[].code === "DEPENDENCY_NOT_FOUND"`
- **原因**：`vendor/yce-engine/yce-engine.mjs` 或其 `node_modules` 不存在（仓库被裁剪、未完整同步）
- **处理**：核对 `meta.dependency_paths.yce-engine-script` 指向的文件存在，且 `vendor/yce-engine/node_modules` 完整

### 7. relay 租 key 失败
- **症状**：`errors[].code === "AUTH_ERROR"`，`--check-key` 报 relay lease failed
- **原因**：未配置 `YCE_RELAY_URL/YCE_RELAY_TOKEN`，或 relay 端点不可用
- **处理**：运行 `install.sh --setup` 写入 YCE 搜索密钥到 `YCE_RELAY_TOKEN`；必要时手动设置 `YCE_API_KEY`；再用 `node ./vendor/yce-engine/yce-engine.mjs --check-key` 验证

### 7.5 YCE 远端 `resource_exhausted`
- **症状**：`errors[].code === "UPSTREAM_ERROR"`，message 包含 `resource_exhausted` / `internal error occurred` / `trace ID`
- **原因**：key 可用但 YCE 远端搜索服务返回资源耗尽或服务端内部错误
- **处理**：YCE 会自动启用 local fast fallback；若必须使用远端语义检索，先用 `node ./vendor/yce-engine/yce-engine.mjs --check-key` 确认 key，再直调 yce-engine 或 fast-context 复现上游错误

### 7.6 yce 有新版本可用
- **症状**：每次执行 yce 时 stderr 末尾出现 `⬆  yce skill 有新版本可用！` 横条，列出本地版本与远端版本
- **原因**：仅当显式设置 `YCE_VERSION_API_URL` 时，`scripts/lib/versionCheck.js` 才会请求版本接口获取远端版本号并与本地比较；默认不再绑定旧接口
- **处理**：执行 `bash $HOME/.agents/skills/yce/install.sh --sync` 升级；如需关闭检查，设置环境变量 `YCE_DISABLE_UPDATE_CHECK=1`

### 8. 把 `--help` 当成正常成功结果
- **症状**：agent 看到 exit code 0，就误以为 YCE 已经正常完成增强 / 检索
- **原因**：`--help` 的 payload 仍然是 XML，而且会强制 pretty-print，但它本质上是帮助结构
- **处理**：同时检查 `<mode>`、`<resolved-action>` 和 `errors.code`；帮助载荷会是空 mode + `INVALID_ARGS`

### 9. 手工 yce-engine 输出被当成 YCE XML 消费
- **症状**：下游 agent 按 `<yce>` 去解析 `yce-engine.mjs` 的输出，结果直接失败
- **原因**：yce-engine 入口只是手工调试入口，不会走 `serializeForStdout()`
- **处理**：需要 XML 契约就调用 `scripts/yce.js`；需要裸 yce-engine 输出再手工调用 `vendor/yce-engine/yce-engine.mjs`

## 安装 / 更新

```bash
# macOS / Linux
bash ./install.sh --install
bash ./install.sh --setup
bash ./install.sh --check
bash ./install.sh --sync
bash ./install.sh --sync-env
bash ./install.sh --uninstall

# Windows PowerShell
.\install.ps1 -Install
.\install.ps1 -Setup
.\install.ps1 -Check
.\install.ps1 -Sync
.\install.ps1 -SyncEnv
.\install.ps1 -Uninstall
```

> 检索引擎已切换为内置的 yce-engine（YCE 本地语义搜索链路）；Windows 下默认写入 `YCE_RELAY_URL=https://yce.aigy.de`，并通过独立的 `YCE_RELAY_TOKEN` 租借 key。

## 打包 / 发布

```bash
# 运行前确保 SKILL.md version 已更新到你要发布的版本
bash ./scripts/build-release.sh
```

发布约束：
- `SKILL.md` 的 `version:` 必须是语义化版本号，例如 `1.6.0`
- `scripts/build-release.sh` 会拒绝“无版本 / 非语义化版本号”的构建
- 打包前会清理旧版本 `dist/yce-skill-v*.tar.gz|zip`，只保留当前版本产物

## 入口与内部模块边界

- **对外 CLI 入口**：
  - `./scripts/yce.js`
  - `./scripts/youwen.js`
- **内部实现模块**：
  - `./scripts/lib/orchestrator.js`
  - `./scripts/lib/utils.js`
  - `./scripts/lib/adapters/yceEngineSearch.js`
  - `./scripts/lib/adapters/ywEnhance.js`
  - `./vendor/yce-engine/`（vendored YCE 语义检索引擎）

规则：
- `YCE_YOUWEN_SCRIPT` 默认应指向 `./scripts/youwen.js`
- `scripts/lib/*` 只给入口脚本 `require()`，**不要**直接配成 `.env` 里的入口路径
- 如果 `meta.dependency_paths.yw_enhance_script` 指到 `scripts/lib`、`scripts/lib/adapters` 或其他目录路径，说明配置错了

## 最后记住

- **每次执行任何代码相关任务，第一步永远是先调用 yce 检索上下文代码**，拿到代码定位之后再做修改 / 分析 / 生成，不得绕过
- yce 检索成功（`result-present="true"`）后，才进入下一步操作；如果检索返回空，先排障再继续，不要盲目直接动手
- 只要任务里同时包含"把问题说清楚"和"去代码库里找实现"，优先先想 `YCE auto`
- 只增强就 `enhance`
- 只定位就 `search`
- 想提高成功率，最关键的不是多写参数，而是 **传对 `--cwd`、在增强场景传 `--history`、并给足超时**
- 真要排障时，优先看 `<resolved-action>`、`<search><query>`、`<meta><dependency-paths>`，不要先凭感觉猜链路
- 调用顺序口诀：**先 yce 检索 → 看结果 → 再动手**，此顺序不可颠倒