@fkqfkq123/opencode-autopilot 0.1.3 → 0.1.5

package/GUIDE.zh-CN.md

@@ -0,0 +1,465 @@
+# Autopilot
+
+[English](./README.md) | 中文说明
+
+Autopilot 是一个面向 OpenCode 风格运行时的 **attached-session workflow harness**。它提供从需求精炼、计划、开发、评审到测试的 workflow runtime 骨架，以及可本地加载的插件、CLI 入口和诊断能力。
+
+## 1. 这个项目提供什么
+
+- 完整 workflow phase 主链：`spec_refinement -> plan -> develop -> review -> test -> done`
+- 面向 OpenCode 的 workflow 命令：`workflow_open`、`workflow_attach`、`workflow_status`、`workflow_answer`、`workflow_approve`、`workflow_resume`、`workflow_back`
+- OpenCode 风格宿主的插件加载能力与原生 primary workflow agent 注册能力
+- `install` / `doctor` 初始化与自检流程
+- review/test loop-back、人工断点、事件存储、attach / re-attach 支持
+
+## 2. 适合谁使用
+
+如果你希望：
+
+- 在 OpenCode 风格宿主中接入 workflow 主代理
+- 把工程流程拆成显式 phase
+- 通过插件形式验证 workflow runtime 与 command surface
+
+那么这个项目适合你。
+
+## 3. 环境准备
+
+建议环境：
+
+- macOS / Linux / Windows
+- [Bun](https://bun.sh/) `1.3.5` 或兼容版本
+- 已安装 OpenCode（如果你需要实际加载并验证插件）
+
+检查 Bun：
+
+```bash
+bun --version
+```
+
+如果还没有安装 Bun：
+
+```bash
+curl -fsSL https://bun.sh/install | bash
+```
+
+安装完成后重启终端，再执行：
+
+```bash
+bun --version
+```
+
+## 4. 安装
+
+### 4.1 推荐方式：作为 npm 插件包安装
+
+OpenCode 原生支持 npm 插件。等这个包发布后，最简单的配置方式是：
+
+```json
+{
+  "plugin": ["@fkqfkq123/opencode-autopilot"]
+}
+```
+
+也可以固定版本：
+
+```json
+{
+  "plugin": ["@fkqfkq123/opencode-autopilot@0.1.2"]
+}
+```
+
+在这种模式下，OpenCode 会自动安装并缓存 npm 包，不需要手动 `git clone`、不需要本地 `plugin.js`、也不需要额外安装脚本。
+
+### 4.2 备用方式：通过 GitHub Releases 安装
+
+如果你更希望走本地文件安装路径，或者需要 fallback 分发方式，可以使用 GitHub Releases 一键安装脚本：
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/juhuaxia/Autopilot/main/install.sh | bash
+```
+
+安装指定版本：
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/juhuaxia/Autopilot/main/install.sh | bash -s -- --version v0.1.2
+```
+
+这个备用安装脚本会：
+
+- 从 GitHub Releases 下载预构建发布包
+- 安装到 `~/.config/opencode/plugins/autopilot/`
+- 更新 `~/.config/opencode/opencode.json`
+
+发布要求：
+
+- 每个 GitHub Release 需要包含 `autopilot-release.tar.gz`
+- 仓库内置 `.github/workflows/release.yml`，在推送 `v*` tag 时会自动构建并上传该文件
+
+如果你想修改源码或从源码开发，继续看下面的源码安装流程。
+
+### 4.3 克隆仓库
+
+```bash
+git clone https://github.com/juhuaxia/Autopilot.git
+cd Autopilot
+```
+
+### 4.4 安装依赖
+
+```bash
+bun install
+```
+
+项目使用 `bun.lock`，依赖版本应保持可复现。
+
+## 5. 推荐首次执行的命令
+
+在项目根目录执行：
+
+```bash
+bun run src/cli.ts install
+bun run src/cli.ts doctor
+bun run build
+```
+
+它们分别会：
+
+1. `install`
+   - 创建项目级 `.workflow-harness/autopilot.json`
+   - 在缺失时创建全局 `~/.config/opencode/autopilot.json`
+   - 尝试安全写入 `~/.config/opencode/opencode.json`
+   - 如有 `opencode.jsonc`，在安全情况下归一化写回 `opencode.json`
+2. `doctor`
+   - 检查 `autopilot.json`
+   - 检查 `skillRoots`
+   - 检查各 phase 的 `requiredSkills`
+   - 输出告警与缺失项
+3. `build`
+   - 编译 TypeScript
+   - 生成 `dist/plugin.js`
+
+之后建议确认：
+
+- `.workflow-harness/autopilot.json` 已生成
+- `doctor` 没有阻断性配置问题
+- `dist/plugin.js` 已生成
+
+## 6. 常用开发命令
+
+### 6.1 构建
+
+```bash
+bun run build
+```
+
+### 6.2 类型检查
+
+```bash
+bun run typecheck
+```
+
+### 6.3 运行测试
+
+```bash
+bun test
+```
+
+### 6.4 运行插件 smoke test
+
+```bash
+bun run smoke:plugin
+```
+
+### 6.5 直接运行 CLI
+
+```bash
+bun run src/cli.ts doctor
+bun run src/cli.ts install
+```
+
+也可以通过脚本别名运行：
+
+```bash
+bun run cli --help
+```
+
+> CLI 主要用于 workflow 初始化、attach/status 流程以及 install/doctor 动作。
+
+## 7. CLI 快速使用
+
+### 7.1 初始化配置
+
+```bash
+bun run src/cli.ts install
+```
+
+### 7.2 做一次自检
+
+```bash
+bun run src/cli.ts doctor
+```
+
+### 7.3 创建一个 workflow
+
+```bash
+bun run src/cli.ts workflow-open wf-1
+```
+
+### 7.4 查看 workflow 状态
+
+```bash
+bun run src/cli.ts workflow-status wf-1
+```
+
+### 7.5 重新 attach 到 workflow channel
+
+```bash
+bun run src/cli.ts workflow-attach wf-1
+```
+
+## 8. 如何把插件加载到 OpenCode
+
+### 8.0 推荐的 npm 插件方式
+
+推荐的 OpenCode 配置：
+
+```json
+{
+  "plugin": ["@fkqfkq123/opencode-autopilot"]
+}
+```
+
+### 8.1 备用的 release 安装方式
+
+如果你希望使用本地安装后的 fallback 插件，执行：
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/juhuaxia/Autopilot/main/install.sh | bash
+```
+
+默认安装位置：
+
+```txt
+~/.config/opencode/plugins/autopilot/
+```
+
+安装脚本会写入类似这样的插件入口：
+
+```txt
+file:///Users/<your-user>/.config/opencode/plugins/autopilot/plugin.js
+```
+
+### 8.2 源码开发方式
+
+执行：
+
+```bash
+bun run src/cli.ts install
+bun run src/cli.ts doctor
+```
+
+如果 installer 能安全改写 OpenCode 配置，通常不需要手工编辑。
+
+> `install.sh` 面向 GitHub Releases 安装；项目内 installer 面向源码开发场景。
+
+### 8.3 手工注册插件
+
+OpenCode 配置通常在：
+
+- `~/.config/opencode/opencode.json`
+- 或 `~/.config/opencode/opencode.jsonc`
+
+#### 方案 A：加载构建产物
+
+先构建：
+
+```bash
+bun run build
+```
+
+然后在 OpenCode 配置中加入：
+
+```json
+{
+  "plugin": [
+    "file:///ABSOLUTE_PATH_TO_PROJECT/dist/plugin.js"
+  ]
+}
+```
+
+#### 方案 B：开发阶段直接加载源码
+
+```json
+{
+  "plugin": [
+    "file:///ABSOLUTE_PATH_TO_PROJECT/plugin.ts"
+  ]
+}
+```
+
+### 8.4 启动 OpenCode
+
+交互模式：
+
+```bash
+opencode
+```
+
+Server 模式：
+
+```bash
+opencode serve
+```
+
+## 9. 加载成功后你应该看到什么
+
+插件会暴露这些工具/命令：
+
+- `workflow_channel`
+- `workflow_open`
+- `workflow_attach`
+- `workflow_status`
+- `workflow_answer`
+- `workflow_approve`
+- `workflow_resume`
+- `workflow_back`
+- `workflow_doctor`
+
+推荐优先使用 split tools：
+
+- `workflow_open`
+- `workflow_attach`
+- `workflow_status`
+- `workflow_answer`
+- `workflow_approve`
+- `workflow_resume`
+- `workflow_back`
+
+典型加载日志：
+
+```txt
+[autopilot] Autopilot plugin loaded (... commands)
+```
+
+## 10. 目录结构
+
+### 10.1 配置层级
+
+- 用户默认：`~/.config/opencode/autopilot.json`
+- 项目级覆盖：`<repo>/.workflow-harness/autopilot.json`
+- 运行时状态：`<repo>/.workflow-harness/workflows/<workflowId>/`
+
+### 10.2 各目录作用
+
+- `src/` — CLI 入口与顶层源码
+- `packages/runtime/` — workflow runtime 实现
+- `tests/` — 测试
+- `scripts/` — 辅助脚本
+- `.workflow-harness/` — 运行时配置、状态与产物
+- `dist/` — 构建输出
+
+## 11. 最小 `autopilot.json` 示例
+
+先从完全中性的配置开始：
+
+```json
+{
+  "skillRoots": ["~/.claude/skills", "~/.config/opencode/skills"],
+  "phases": {
+    "develop": { "requiredSkills": [] },
+    "test": { "requiredSkills": [] }
+  }
+}
+```
+
+然后按项目需要添加 skill。以前端项目为例：
+
+```json
+{
+  "skillRoots": ["~/.claude/skills", "~/.config/opencode/skills"],
+  "phases": {
+    "develop": { "requiredSkills": ["frontend-design"] },
+    "test": { "requiredSkills": ["playwright"] }
+  }
+}
+```
+
+这个前端示例只是示例，workflow runtime 默认并不绑定前端。
+
+建议：
+
+- skill / profile 配置放在全局或项目级 `autopilot.json`
+- 不要把 skill 配置写到 `workflows/<workflowId>/`
+- 新配置上线前先跑 `workflow_doctor` 或 CLI `doctor`
+
+## 12. 常见问题
+
+### Q1：`install` 无法改写 OpenCode 配置怎么办？
+
+手工编辑 OpenCode 配置，把发布版插件路径或本地构建路径加入 `plugin` 数组。例如：
+
+```json
+{
+  "plugin": [
+    "file:///Users/<your-user>/.config/opencode/plugins/autopilot/plugin.js"
+  ]
+}
+```
+
+如果你是源码开发场景，也可以指向本地的 `dist/plugin.js`。
+
+如果你使用 npm 插件模式，则只需要这样配置：
+
+```json
+{
+  "plugin": ["@fkqfkq123/opencode-autopilot"]
+}
+```
+
+### Q2：为什么 build 以后还是看不到 workflow 命令？
+
+通常是宿主集成层还没有把导出的 `workflowCommands` 真正注册到宿主命令面板 / tool surface。
+
+### Q3：我应该先验证什么？
+
+建议先按这个顺序验证：
+
+1. 宿主能导入插件文件
+2. 宿主能调用默认导出
+3. 宿主能收到一个 plugin-like 对象
+
+不要一开始就先验证 UI。
+
+### Q4：插件根入口有什么约束？
+
+根入口 `plugin.ts` 应只暴露一个宿主可调用的默认导出，不要在根入口额外暴露内部 class 或 helper function。
+
+## 13. 推荐阅读
+
+| 文档 | 用途 |
+|---|---|
+| `README.md` | 安装、发布、使用总入口 |
+| `WORKFLOW_SKILL_PROFILE_ARCHITECTURE_CN.md` | skill / profile 配置设计 |
+| `OPENCODE_WORKFLOW_AGENT_GUIDE.md` | agent / tool 调用顺序 |
+| `REQUIREMENT_TEMPLATE.md` | 需求输入模板 |
+
+内部规划稿、验收草案、状态记录等可以保存在本地 `docs_internal/` 中，该目录默认已忽略。
+
+## 14. 最快可用路径
+
+如果你只想最快跑起源码开发环境：
+
+```bash
+bun install
+bun run src/cli.ts install
+bun run src/cli.ts doctor
+bun run build
+opencode
+```
+
+然后：
+
+1. 确认 `.workflow-harness/autopilot.json` 已生成
+2. 确认 `dist/plugin.js` 已生成
+3. 如果 OpenCode 没有自动加载插件，手工把 `file:///ABSOLUTE_PATH_TO_PROJECT/dist/plugin.js` 加到配置里
+4. 在宿主中验证 `workflow_open`、`workflow_attach`、`workflow_status` 是否可见

package/README.md

@@ -123,11 +123,12 @@ bun run build
 What they do:
 
 1. `install`
-   - creates project-level `.workflow-harness/workflow.json`
+   - creates project-level `.workflow-harness/autopilot.json`
+   - creates global `~/.config/opencode/autopilot.json` when missing
    - tries to safely update `~/.config/opencode/opencode.json`
    - normalizes `opencode.jsonc` into `opencode.json` when safe
 2. `doctor`
-   - checks `workflow.json`
+   - checks `autopilot.json`
    - checks `skillRoots`
    - checks phase-level `requiredSkills`
    - reports warnings and missing pieces
@@ -137,7 +138,7 @@ What they do:
 
 After that, confirm:
 
-- `.workflow-harness/workflow.json` exists
+- `.workflow-harness/autopilot.json` exists
 - `doctor` shows no blocking configuration issue
 - `dist/plugin.js` exists
 
@@ -342,8 +343,8 @@ Typical load log:
 
 ### 10.1 Configuration layers
 
-- user default: `~/.config/opencode/workflow.json`
-- project override: `<repo>/.workflow-harness/workflow.json`
+- user default: `~/.config/opencode/autopilot.json`
+- project override: `<repo>/.workflow-harness/autopilot.json`
 - runtime state: `<repo>/.workflow-harness/workflows/<workflowId>/`
 
 ### 10.2 What each directory does
@@ -355,7 +356,7 @@ Typical load log:
 - `.workflow-harness/` — runtime config, state, and artifacts
 - `dist/` — build output
 
-## 11. Minimal `workflow.json` example
+## 11. Minimal `autopilot.json` example
 
 Start with a fully neutral config:
 
@@ -385,7 +386,7 @@ That frontend example is only an example. The workflow runtime is not frontend-b
 
 Recommendations:
 
-- keep skill/profile config in global or project-level `workflow.json`
+- keep skill/profile config in global or project-level `autopilot.json`
 - do not put skill config under `workflows/<workflowId>/`
 - run `workflow_doctor` or CLI `doctor` before using a new config
 
@@ -456,7 +457,7 @@ opencode
 
 Then:
 
-1. confirm `.workflow-harness/workflow.json` exists
+1. confirm `.workflow-harness/autopilot.json` exists
 2. confirm `dist/plugin.js` exists
 3. if OpenCode does not auto-load the plugin, add `file:///ABSOLUTE_PATH_TO_PROJECT/dist/plugin.js` manually to config
 4. verify `workflow_open`, `workflow_attach`, and `workflow_status` are visible in the host

package/dist/packages/runtime/src/bootstrap/create-harness.js

@@ -1,11 +1,12 @@
 import { mkdir } from "node:fs/promises";
+import { homedir } from "node:os";
 import { join } from "node:path";
 import { HttpOpencodeSessionClient, InMemoryOpencodeSessionClient, } from "../../../adapters/opencode/src/opencode-session-client";
 import { DefaultPhaseTransition } from "../../../core/src/transitions/default-phase-transition";
 import { FileSystemArtifactEvaluator } from "../artifacts/file-system-artifact-evaluator";
 import { DefaultAttachService } from "../attach/attach-service";
 import { buildSkillRegistryWithWarnings } from "../config/skill-registry";
-import { resolveWorkflowConfig } from "../config/workflow-config";
+import { ensureAutopilotConfigFile, resolveWorkflowConfig, AUTOPILOT_CONFIG_FILENAME } from "../config/workflow-config";
 import { DefaultWorkflowEngine } from "../engine/default-workflow-engine";
 import { FileSystemWorkflowEventStore } from "../events/file-system-workflow-event-store";
 import { BasicRecoveryClassifier } from "../recovery/basic-recovery-classifier";
@@ -20,6 +21,8 @@ import { DefaultWorkflowWorkspace } from "../workspace/workflow-workspace";
 export async function createHarness(baseDir, options = {}) {
     await mkdir(join(baseDir, "workflows"), { recursive: true });
     const workspace = new DefaultWorkflowWorkspace(baseDir);
+    await ensureAutopilotConfigFile(workspace.workflowConfigFile());
+    await ensureAutopilotConfigFile(join(homedir(), ".config", "opencode", AUTOPILOT_CONFIG_FILENAME));
     const resolvedConfig = await resolveWorkflowConfig({
         projectConfigFile: workspace.workflowConfigFile(),
     });

package/dist/packages/runtime/src/config/workflow-config.d.ts

@@ -1,3 +1,6 @@
+export declare const AUTOPILOT_CONFIG_FILENAME = "autopilot.json";
+export declare const LEGACY_WORKFLOW_CONFIG_FILENAME = "workflow.json";
+export declare const DEFAULT_SKILL_ROOTS: string[];
 export type WorkflowConfigPhase = "spec_refinement" | "plan" | "develop" | "review" | "test";
 export type WorkflowPhaseConfig = {
     requiredSkills?: string[];
@@ -11,7 +14,9 @@ export type ResolvedWorkflowConfig = {
     phases: Partial<Record<WorkflowConfigPhase, WorkflowPhaseConfig>>;
     warnings: string[];
 };
+export declare const DEFAULT_AUTOPILOT_CONFIG: WorkflowConfigFile;
 export declare function resolveWorkflowConfig(args: {
     projectConfigFile: string;
     homeDir?: string;
 }): Promise<ResolvedWorkflowConfig>;
+export declare function ensureAutopilotConfigFile(filePath: string): Promise<void>;

package/dist/packages/runtime/src/config/workflow-config.js

@@ -1,6 +1,20 @@
+import { readFile } from "node:fs/promises";
 import { homedir } from "node:os";
-import { join } from "node:path";
-import { readJsonFile } from "../shared/json-file";
+import { dirname, join } from "node:path";
+import { fileExists, readJsonFile, writeJsonFile } from "../shared/json-file";
+export const AUTOPILOT_CONFIG_FILENAME = "autopilot.json";
+export const LEGACY_WORKFLOW_CONFIG_FILENAME = "workflow.json";
+export const DEFAULT_SKILL_ROOTS = ["~/.claude/skills", "~/.config/opencode/skills"];
+export const DEFAULT_AUTOPILOT_CONFIG = {
+    skillRoots: DEFAULT_SKILL_ROOTS,
+    phases: {
+        spec_refinement: { requiredSkills: [] },
+        plan: { requiredSkills: [] },
+        develop: { requiredSkills: [] },
+        review: { requiredSkills: [] },
+        test: { requiredSkills: [] },
+    },
+};
 const EMPTY_CONFIG = {
     skillRoots: [],
     phases: {},
@@ -43,9 +57,84 @@ function mergeConfigs(base, incoming) {
     }
     return next;
 }
+async function readConfigFileWithWarnings(filePath, label) {
+    if (!(await fileExists(filePath))) {
+        return { config: null, warnings: [] };
+    }
+    try {
+        const raw = await readFile(filePath, "utf8");
+        if (!raw.trim()) {
+            return {
+                config: null,
+                warnings: [`${label} is empty and will be treated as defaults: ${filePath}`],
+            };
+        }
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+            return {
+                config: null,
+                warnings: [`${label} is not a JSON object and will be ignored: ${filePath}`],
+            };
+        }
+        return {
+            config: parsed,
+            warnings: [],
+        };
+    }
+    catch (error) {
+        if (error instanceof SyntaxError) {
+            return {
+                config: null,
+                warnings: [`${label} contains invalid JSON and will be ignored: ${filePath}`],
+            };
+        }
+        throw error;
+    }
+}
+async function loadConfigWithLegacy(args) {
+    const preferred = await readConfigFileWithWarnings(args.preferredFile, args.label);
+    if (preferred.config || preferred.warnings.length > 0 || await fileExists(args.preferredFile)) {
+        return preferred;
+    }
+    const legacy = await readConfigFileWithWarnings(args.legacyFile, `Legacy ${args.label}`);
+    if (!legacy.config && legacy.warnings.length === 0) {
+        return legacy;
+    }
+    return {
+        config: legacy.config,
+        warnings: [
+            `Using legacy ${LEGACY_WORKFLOW_CONFIG_FILENAME}; migrate to ${AUTOPILOT_CONFIG_FILENAME}: ${args.legacyFile}`,
+            ...legacy.warnings,
+        ],
+    };
+}
 export async function resolveWorkflowConfig(args) {
-    const globalConfigFile = join(args.homeDir ?? homedir(), ".config", "opencode", "workflow.json");
-    const globalConfig = await readJsonFile(globalConfigFile);
-    const projectConfig = await readJsonFile(args.projectConfigFile);
-    return mergeConfigs(mergeConfigs(EMPTY_CONFIG, globalConfig), projectConfig);
+    const globalConfigFile = join(args.homeDir ?? homedir(), ".config", "opencode", AUTOPILOT_CONFIG_FILENAME);
+    const globalLegacyFile = join(args.homeDir ?? homedir(), ".config", "opencode", LEGACY_WORKFLOW_CONFIG_FILENAME);
+    const projectLegacyFile = join(dirname(args.projectConfigFile), LEGACY_WORKFLOW_CONFIG_FILENAME);
+    const globalConfig = await loadConfigWithLegacy({
+        preferredFile: globalConfigFile,
+        legacyFile: globalLegacyFile,
+        label: `Global ${AUTOPILOT_CONFIG_FILENAME}`,
+    });
+    const projectConfig = await loadConfigWithLegacy({
+        preferredFile: args.projectConfigFile,
+        legacyFile: projectLegacyFile,
+        label: `Project ${AUTOPILOT_CONFIG_FILENAME}`,
+    });
+    const merged = mergeConfigs(mergeConfigs(EMPTY_CONFIG, globalConfig.config), projectConfig.config);
+    merged.warnings.push(...globalConfig.warnings, ...projectConfig.warnings);
+    return merged;
+}
+export async function ensureAutopilotConfigFile(filePath) {
+    if (await fileExists(filePath)) {
+        return;
+    }
+    const legacyFilePath = join(dirname(filePath), LEGACY_WORKFLOW_CONFIG_FILENAME);
+    const legacyConfig = await readJsonFile(legacyFilePath);
+    if (legacyConfig) {
+        await writeJsonFile(filePath, legacyConfig);
+        return;
+    }
+    await writeJsonFile(filePath, DEFAULT_AUTOPILOT_CONFIG);
 }

package/dist/packages/runtime/src/diagnostics/workflow-diagnostics-format.js

@@ -1,3 +1,4 @@
+import { AUTOPILOT_CONFIG_FILENAME } from "../config/workflow-config";
 const divider = "=".repeat(64);
 export function formatWorkflowDoctorResult(result) {
     const lines = [
@@ -50,7 +51,7 @@ export function formatWorkflowInstallResult(result) {
     const lines = [
         divider,
         `Workflow Install: ${result.ok ? "OK" : "ATTENTION"}`,
-        `Project workflow.json: ${result.projectWorkflowConfigFile}`,
+        `Project ${AUTOPILOT_CONFIG_FILENAME}: ${result.projectWorkflowConfigFile}`,
         `OpenCode config: ${result.opencodeConfigFile}`,
         `Plugin entry: ${result.pluginEntry}`,
     ];

package/dist/packages/runtime/src/diagnostics/workflow-doctor.js

@@ -3,7 +3,7 @@ import { readFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { buildSkillRegistryWithWarnings } from "../config/skill-registry";
-import { resolveWorkflowConfig } from "../config/workflow-config";
+import { AUTOPILOT_CONFIG_FILENAME, resolveWorkflowConfig } from "../config/workflow-config";
 async function fileExists(filePath) {
     try {
         await access(filePath);
@@ -29,7 +29,7 @@ function gitignoreHasWorkflowHarness(content) {
 }
 export async function runWorkflowDoctor(workspace) {
     const projectConfigFile = workspace.workflowConfigFile();
-    const globalConfigFile = join(homedir(), ".config", "opencode", "workflow.json");
+    const globalConfigFile = join(homedir(), ".config", "opencode", AUTOPILOT_CONFIG_FILENAME);
     const resolvedConfig = await resolveWorkflowConfig({
         projectConfigFile,
     });
@@ -52,7 +52,7 @@ export async function runWorkflowDoctor(workspace) {
     }
     const hasGlobalConfig = await fileExists(globalConfigFile);
     if (!hasGlobalConfig) {
-        warnings.push(`Global workflow.json not found: ${globalConfigFile}`);
+        warnings.push(`Global ${AUTOPILOT_CONFIG_FILENAME} not found: ${globalConfigFile}`);
     }
     const workspaceRoot = workspace.baseDir().endsWith(".workflow-harness")
         ? dirname(workspace.baseDir())
@@ -91,10 +91,10 @@ export async function runWorkflowDoctor(workspace) {
     });
     const nextSteps = [];
     if (!(await fileExists(projectConfigFile))) {
-        nextSteps.push(`Run installer to generate project workflow.json: ${projectConfigFile}`);
+        nextSteps.push(`Run installer to generate project ${AUTOPILOT_CONFIG_FILENAME}: ${projectConfigFile}`);
     }
     if (resolvedConfig.skillRoots.length === 0) {
-        nextSteps.push("Add skillRoots to workflow.json if you want phase skill injection");
+        nextSteps.push(`Add skillRoots to ${AUTOPILOT_CONFIG_FILENAME} if you want phase skill injection`);
     }
     if (missingSkills.length > 0) {
         nextSteps.push("Fix missing requiredSkills or add corresponding skill files under configured skillRoots");

package/dist/packages/runtime/src/install/workflow-installer.js

@@ -1,23 +1,7 @@
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { join, resolve } from "node:path";
-import { access } from "node:fs/promises";
-import { writeJsonFile } from "../shared/json-file";
-const DEFAULT_WORKFLOW_CONFIG = {
-    skillRoots: ["~/.claude/skills", "~/.config/opencode/skills"],
-    phases: {
-        develop: { requiredSkills: [] },
-        test: { requiredSkills: [] },
-    },
-};
-async function fileExists(filePath) {
-    try {
-        await access(filePath);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
+import { ensureAutopilotConfigFile, AUTOPILOT_CONFIG_FILENAME } from "../config/workflow-config";
+import { fileExists, writeJsonFile } from "../shared/json-file";
 function stripJsonComments(input) {
     return input
         .replace(/^\s*\/\/.*$/gm, "")
@@ -44,18 +28,18 @@ async function resolveOpencodeConfigFile(opencodeConfigDir) {
 export async function runWorkflowInstall(args) {
     const repoRoot = resolve(args.cwd);
     const harnessDir = join(repoRoot, ".workflow-harness");
-    const projectWorkflowConfigFile = join(harnessDir, "workflow.json");
+    const projectWorkflowConfigFile = join(harnessDir, AUTOPILOT_CONFIG_FILENAME);
     const opencodeConfigDir = join(args.homeDir, ".config", "opencode");
+    const globalAutopilotConfigFile = join(opencodeConfigDir, AUTOPILOT_CONFIG_FILENAME);
     const pluginEntryFile = args.options?.pluginEntryFile ?? "dist/plugin.js";
     const pluginEntry = `file://${join(repoRoot, pluginEntryFile)}`;
     const configResolution = await resolveOpencodeConfigFile(opencodeConfigDir);
     const opencodeConfigFile = join(opencodeConfigDir, "opencode.json");
     const warnings = [...configResolution.warnings];
     await mkdir(harnessDir, { recursive: true });
-    if (!(await fileExists(projectWorkflowConfigFile))) {
-        await writeJsonFile(projectWorkflowConfigFile, DEFAULT_WORKFLOW_CONFIG);
-    }
+    await ensureAutopilotConfigFile(projectWorkflowConfigFile);
     await mkdir(opencodeConfigDir, { recursive: true });
+    await ensureAutopilotConfigFile(globalAutopilotConfigFile);
     if (!(await fileExists(configResolution.filePath))) {
         await writeJsonFile(opencodeConfigFile, {
             plugin: [pluginEntry],

package/dist/packages/runtime/src/plugin/workflow-plugin-entry.js

@@ -5,10 +5,11 @@ import { createHarness } from "../bootstrap/create-harness";
 import { runWorkflowDoctor } from "../diagnostics/workflow-doctor";
 import { runWorkflowInstall } from "../install/workflow-installer";
 import { SdkOpencodeSessionClient, } from "../../../adapters/opencode/src/opencode-session-client";
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { mkdir, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
-import { join } from "node:path";
 import { z } from "zod";
+import { readJsonFile } from "../shared/json-file";
+import { DefaultWorkflowWorkspace } from "../workspace/workflow-workspace";
 const workflowIdSchema = z.string().min(1).describe("Workflow identifier");
 const WORKFLOW_PRIMARY_AGENT_PROMPT = `You are the workflow execution agent.
 
@@ -77,14 +78,8 @@ async function syncHostTodos(args) {
     if (!todoClient?.list || !todoClient.create || !todoClient.update) {
         return;
     }
-    const stateFile = join(args.baseDir, "workflows", args.workflowId, "workflow-state.json");
-    let workflow = null;
-    try {
-        workflow = JSON.parse(await readFile(stateFile, "utf8"));
-    }
-    catch {
-        return;
-    }
+    const workspace = new DefaultWorkflowWorkspace(args.baseDir);
+    const workflow = await readJsonFile(workspace.workflowStateFile(args.workflowId));
     if (!workflow?.activeSessionId || !workflow.phase || !workflow.status) {
         return;
     }
@@ -320,7 +315,7 @@ export async function workflowPlugin(input) {
                 },
             },
             workflow_install: {
-                description: "Generate workflow.json and safely register the plugin in OpenCode config.",
+                description: "Generate autopilot.json and safely register the plugin in OpenCode config.",
                 args: {},
                 execute: async () => {
                     return JSON.stringify(await runWorkflowInstall({

package/dist/packages/runtime/src/shared/json-file.d.ts

@@ -1,2 +1,3 @@
+export declare function fileExists(filePath: string): Promise<boolean>;
 export declare function readJsonFile<T>(filePath: string): Promise<T | null>;
 export declare function writeJsonFile(filePath: string, value: unknown): Promise<void>;

package/dist/packages/runtime/src/shared/json-file.js

@@ -1,5 +1,14 @@
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname } from "node:path";
+export async function fileExists(filePath) {
+    try {
+        await access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 export async function readJsonFile(filePath) {
     try {
         const raw = await readFile(filePath, "utf8");

package/dist/packages/runtime/src/workspace/workflow-workspace.js

@@ -1,4 +1,5 @@
 import { join } from "node:path";
+import { AUTOPILOT_CONFIG_FILENAME } from "../config/workflow-config";
 export class DefaultWorkflowWorkspace {
     root;
     constructor(root) {
@@ -9,6 +10,9 @@ export class DefaultWorkflowWorkspace {
         if (!normalized) {
             throw new Error("workflowId must be a non-empty string");
         }
+        if (normalized.includes("..") || normalized.includes("/") || normalized.includes("\\")) {
+            throw new Error("workflowId must not contain path separators or traversal sequences");
+        }
         return normalized;
     }
     baseDir() {
@@ -18,7 +22,7 @@ export class DefaultWorkflowWorkspace {
         return join(this.root, "workflows");
     }
     workflowConfigFile() {
-        return join(this.root, "workflow.json");
+        return join(this.root, AUTOPILOT_CONFIG_FILENAME);
     }
     workflowDir(workflowId) {
         return join(this.workflowsRoot(), this.normalizeWorkflowId(workflowId));

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fkqfkq123/opencode-autopilot",
   "private": false,
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "An OpenCode plugin for attached-session workflow execution with refinement, planning, development, review, and test phases.",
   "type": "module",
   "packageManager": "bun@1.3.5",
@@ -24,7 +24,8 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "GUIDE.zh-CN.md"
   ],
   "publishConfig": {
     "access": "public"