opencode-workspace-scope 0.1.0

package/README.md

@@ -0,0 +1,95 @@
+# opencode-workspace-scope
+
+全局安装、**sidecar 自激活**的 [opencode](https://opencode.ai) 插件，为多 git worktree 并行开发提供工作区作用域隔离。
+
+每个并行工作区在 `.opencode/workspace-scope.jsonc` 里声明本工作区涉及的 worktree 路径与职责，插件据此：
+
+- 自动注入 `permission.external_directory` 白名单，**只放开本工作区的 worktree**，其余外部路径保持默认 ask；
+- 把"工作区根 + 各 worktree 路径及职责"注入 system prompt，让 AI 每轮都知道改哪里、哪些路径不能碰。
+
+无 sidecar 的项目中插件完全 no-op，不影响任何正常使用。
+
+## 安装
+
+全局安装（推荐，配合 sidecar 自激活）：
+
+```bash
+mkdir -p ~/.config/opencode/plugins
+ln -s /path/to/opencode-workspace-scope/src/index.ts ~/.config/opencode/plugins/workspace-scope.ts
+# 或按项目使用 npm：
+# npm install opencode-workspace-scope
+```
+
+重启 opencode 后生效。
+
+## 快速开始
+
+1. 在某个工作区根目录启动 opencode，对它说：
+
+   > 初始化这个工作区的 scope 配置
+
+   插件会调用 `workspace_scope_init` 工具：自动探测父目录下的兄弟 git 仓库作为候选 worktree，生成 `.opencode/workspace-scope.jsonc`（并自动写入 `.opencode/.gitignore`，不纳入版本管理），同时生成配套 JSON Schema。
+
+2. 编辑该文件，为每个 worktree 补充 `description`（职责说明，会注入 AI 上下文）：
+
+   ```jsonc
+   {
+     "$schema": "./workspace-scope.schema.json",
+     "name": "feature-x",
+     "workspace": {
+       "path": "/home/you/dev/wsp/feature-x",
+       "description": "编排根：opencode 配置/规则所在地"
+     },
+     "worktrees": [
+       { "name": "frontend", "path": "/home/you/dev/wsp/feature-x/frontend", "description": "前端仓库 React/TS" },
+       { "name": "backend", "path": "../backend", "description": "后端仓库 Go" }
+     ]
+   }
+   ```
+
+   `path` 支持绝对路径，也支持相对**工作区根目录**的相对路径（如 `../backend`）。
+
+3. **重启 opencode**，使 external_directory 权限生效（上下文注入无需重启）。
+
+## 权限行为
+
+- 注入到 `permission.external_directory`：`"<worktree>/**: allow"`，采用"末尾追加、last-match-wins"合并，不覆盖你已有的其他规则；对每个 worktree 同时写入**词法路径与 realpath 两种 pattern**，避免符号链接祖先导致白名单失效；
+- 工作区根目录之外、且不在白名单内的路径：维持 opencode 默认 `ask`；
+- sidecar 中不存在的路径会被跳过，不会崩溃；
+- **sidecar 向上查找**：从启动目录逐级向上找 `.opencode/workspace-scope.jsonc`（最多 10 层），嵌套子项目会继承父工作区的作用域（对齐 opencode 自身配置发现行为）；
+- 注意：`opencode --auto` 会把 `ask` 自动放行。若并行会话需要硬隔离，请在配置里为 `external_directory` 追加 `"*": "deny"` 兜底。
+
+## 注入的上下文
+
+每轮请求会把以下块拼进 system prompt 主块（`output.system[0]`，无 `sessionID` 时不注入）：
+
+```
+## Workspace Scope（由 workspace-scope 插件自动注入）
+当前工作区：feature-x（工作区根：/home/you/dev/wsp/feature-x）
+本次会话的修改范围仅限以下目录，其他路径一律视为外部目录、需用户确认后才可修改：
+- frontend: /home/you/dev/wsp/feature-x/frontend — 前端仓库 React/TS
+- backend: /home/you/dev/wsp/feature-x/backend  — 后端仓库 Go
+```
+
+## 设计约束
+
+- **自激活**：无 sidecar 时插件必须完全 no-op；
+- **权限只押 `external_directory`**：不依赖 read/edit 的路径 pattern（存在绝对/相对不对称问题，见 opencode issue #26524）；
+- **不改默认语义**：用户 `permission` 为字符串缩写（如 `"allow"`）时不改写；对象形式按"末尾追加 allow"合并；
+- **system.transform 原地变更**：只拼 `output.system[0]`，禁止整体赋值（静默 no-op，issue #25754）；
+- **零新增运行时依赖**：仅依赖 `@opencode-ai/plugin`。
+
+## 开发
+
+```bash
+npm install
+npm run typecheck   # tsc --noEmit
+npm run build       # 输出到 dist/
+bun /tmp/opencode/smoke.ts   # 冒烟测试（临时脚本，不入库）
+```
+
+发布：`npm version patch && npm publish`（`prepublishOnly` 自动 typecheck + build）。
+
+## License
+
+MIT

package/dist/context.d.ts

@@ -0,0 +1,2 @@
+import type { ScopeResult } from "./scope.js";
+export declare function buildScopeBlock(scope: ScopeResult): string;

package/dist/context.js

@@ -0,0 +1,13 @@
+export function buildScopeBlock(scope) {
+    const { config } = scope;
+    const lines = [
+        "## Workspace Scope（由 workspace-scope 插件自动注入）",
+        `当前工作区：${config.name}（工作区根：${config.workspace.path}）`,
+        "本次会话的修改范围仅限以下目录，其他路径一律视为外部目录、需用户确认后才可修改：",
+        ...config.worktrees.map((w) => {
+            const desc = w.description ? ` — ${w.description}` : "";
+            return `- ${w.name}: ${w.path}${desc}`;
+        }),
+    ];
+    return lines.join("\n");
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+import type { Plugin } from "@opencode-ai/plugin";
+export declare const WorkspaceScopePlugin: Plugin;
+export default WorkspaceScopePlugin;

package/dist/index.js

@@ -0,0 +1,49 @@
+import { loadScope } from "./scope.js";
+import { buildExternalDirectory, mergePermission } from "./permissions.js";
+import { buildScopeBlock } from "./context.js";
+import { initTool } from "./init.js";
+export const WorkspaceScopePlugin = async ({ directory, worktree, client }) => {
+    const anchor = worktree || directory;
+    const logApplied = (sidecarPath) => {
+        try {
+            const result = client.app?.log?.({
+                body: {
+                    service: "workspace-scope",
+                    level: "info",
+                    message: `已应用工作区作用域 ${sidecarPath}`,
+                },
+            });
+            if (result && typeof result.catch === "function") {
+                result.catch(() => { });
+            }
+        }
+        catch {
+            // ignore
+        }
+    };
+    return {
+        config: async (cfg) => {
+            const scope = loadScope(anchor);
+            if (!scope)
+                return;
+            logApplied(scope.sidecarPath);
+            const external = buildExternalDirectory(scope);
+            if (Object.keys(external).length === 0)
+                return;
+            const anyCfg = cfg;
+            anyCfg.permission = mergePermission(anyCfg.permission, external);
+        },
+        "experimental.chat.system.transform": async (input, output) => {
+            if (!input.sessionID)
+                return;
+            const scope = loadScope(anchor);
+            if (!scope)
+                return;
+            output.system[0] = `${output.system[0] ?? ""}\n\n${buildScopeBlock(scope)}`;
+        },
+        tool: {
+            workspace_scope_init: initTool,
+        },
+    };
+};
+export default WorkspaceScopePlugin;

package/dist/init.d.ts

@@ -0,0 +1,21 @@
+export declare const initTool: {
+    description: string;
+    args: {
+        name: import("zod").ZodOptional<import("zod").ZodString>;
+        workspaceDescription: import("zod").ZodOptional<import("zod").ZodString>;
+        worktrees: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodObject<{
+            name: import("zod").ZodString;
+            path: import("zod").ZodString;
+            description: import("zod").ZodOptional<import("zod").ZodString>;
+        }, import("zod/v4/core").$strip>>>;
+    };
+    execute(args: {
+        name?: string | undefined;
+        workspaceDescription?: string | undefined;
+        worktrees?: {
+            name: string;
+            path: string;
+            description?: string | undefined;
+        }[] | undefined;
+    }, context: import("@opencode-ai/plugin").ToolContext): Promise<import("@opencode-ai/plugin").ToolResult>;
+};

package/dist/init.js

@@ -0,0 +1,110 @@
+import { tool } from "@opencode-ai/plugin";
+import { basename, dirname, join } from "node:path";
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, appendFileSync } from "node:fs";
+import { invalidateScope } from "./scope.js";
+import { WORKSPACE_SCOPE_SCHEMA } from "./schema.js";
+function isGitRepo(p) {
+    return existsSync(join(p, ".git"));
+}
+function detectSiblingRepos(anchor) {
+    const parent = dirname(anchor);
+    let names;
+    try {
+        names = readdirSync(parent, { withFileTypes: true })
+            .filter((d) => d.isDirectory())
+            .map((d) => d.name);
+    }
+    catch {
+        return [];
+    }
+    const selfName = basename(anchor);
+    const out = [];
+    for (const name of names) {
+        if (name === selfName)
+            continue;
+        const p = join(parent, name);
+        if (isGitRepo(p))
+            out.push({ name, path: p });
+    }
+    return out;
+}
+function ensureGitignore(sidecarDir, lines) {
+    const gi = join(sidecarDir, ".gitignore");
+    try {
+        const cur = existsSync(gi) ? readFileSync(gi, "utf8") : "";
+        const existing = cur.split(/\r?\n/);
+        const missing = lines.filter((l) => !existing.includes(l));
+        if (missing.length > 0) {
+            const sep = cur !== "" && !cur.endsWith("\n") ? "\n" : "";
+            appendFileSync(gi, `${sep}${missing.join("\n")}\n`);
+        }
+    }
+    catch {
+        // ignore
+    }
+}
+function writeSchema(sidecarDir) {
+    try {
+        writeFileSync(join(sidecarDir, "workspace-scope.schema.json"), JSON.stringify(WORKSPACE_SCOPE_SCHEMA, null, 2));
+    }
+    catch {
+        // ignore
+    }
+}
+export const initTool = tool({
+    description: "初始化或重建当前工作区的 workspace-scope 配置（.opencode/workspace-scope.jsonc）。不传 worktrees 时自动探测父目录下的兄弟 git 仓库作为候选 worktree。生成的 sidecar 不纳入版本管理（自动写入 .gitignore），并附带 JSON Schema。",
+    args: {
+        name: tool.schema.string().optional().describe("工作区名称，缺省使用当前目录名"),
+        workspaceDescription: tool.schema.string().optional().describe("工作区职责说明"),
+        worktrees: tool.schema
+            .array(tool.schema.object({
+            name: tool.schema.string().describe("仓库名，例如 frontend / backend"),
+            path: tool.schema.string().describe("绝对路径"),
+            description: tool.schema.string().optional().describe("该路径职责说明，会注入 AI 上下文"),
+        }))
+            .optional()
+            .describe("可选：显式指定 worktree 列表；缺省自动探测父目录兄弟 git 仓库"),
+    },
+    async execute(args, context) {
+        const anchor = context.worktree || context.directory;
+        const sidecarDir = join(anchor, ".opencode");
+        mkdirSync(sidecarDir, { recursive: true });
+        const worktrees = args.worktrees && args.worktrees.length > 0 ? args.worktrees : detectSiblingRepos(anchor);
+        if (worktrees.length === 0) {
+            return [
+                "未探测到兄弟 git 仓库，也未收到显式 worktrees 参数。",
+                "请传入 worktrees（name+path+description），或确认已在 workspace 根目录启动 opencode。",
+            ].join("\n");
+        }
+        const filePath = join(sidecarDir, "workspace-scope.jsonc");
+        const content = {
+            $schema: "./workspace-scope.schema.json",
+            name: args.name || basename(anchor),
+            workspace: {
+                path: anchor,
+                description: args.workspaceDescription,
+            },
+            worktrees: worktrees.map((w) => ({
+                name: w.name,
+                path: w.path,
+                description: w.description,
+            })),
+        };
+        writeFileSync(filePath, JSON.stringify(content, null, 2));
+        writeSchema(sidecarDir);
+        ensureGitignore(sidecarDir, ["workspace-scope.jsonc", "workspace-scope.schema.json"]);
+        invalidateScope();
+        return [
+            `已生成 ${filePath}`,
+            "",
+            "内容：",
+            "```jsonc",
+            JSON.stringify(content, null, 2),
+            "```",
+            "",
+            "下一步：",
+            "1. 编辑该文件，为每个 worktree 补充 description（职责说明，会注入 AI 上下文）；",
+            "2. 重启 opencode 使 external_directory 权限生效（上下文注入无需重启）。",
+        ].join("\n");
+    },
+});

package/dist/jsonc.d.ts

@@ -0,0 +1 @@
+export declare function parseJsonc(text: string): unknown;

package/dist/jsonc.js

@@ -0,0 +1,87 @@
+function stripComments(text) {
+    let out = "";
+    let inString = false;
+    let i = 0;
+    while (i < text.length) {
+        const c = text[i];
+        const n = text[i + 1];
+        if (inString) {
+            out += c;
+            if (c === "\\" && n !== undefined) {
+                out += n;
+                i += 2;
+                continue;
+            }
+            if (c === '"')
+                inString = false;
+            i += 1;
+            continue;
+        }
+        if (c === '"') {
+            inString = true;
+            out += c;
+            i += 1;
+            continue;
+        }
+        if (c === "/" && n === "/") {
+            while (i < text.length && text[i] !== "\n")
+                i += 1;
+            continue;
+        }
+        if (c === "/" && n === "*") {
+            i += 2;
+            while (i < text.length && !(text[i] === "*" && text[i + 1] === "/"))
+                i += 1;
+            i += 2;
+            continue;
+        }
+        out += c;
+        i += 1;
+    }
+    return out;
+}
+function stripTrailingCommas(text) {
+    let out = "";
+    let inString = false;
+    let i = 0;
+    while (i < text.length) {
+        const c = text[i];
+        if (inString) {
+            out += c;
+            if (c === "\\") {
+                const n = text[i + 1];
+                if (n !== undefined) {
+                    out += n;
+                    i += 1;
+                }
+            }
+            else if (c === '"') {
+                inString = false;
+            }
+            i += 1;
+            continue;
+        }
+        if (c === '"') {
+            inString = true;
+            out += c;
+            i += 1;
+            continue;
+        }
+        if (c === ",") {
+            let j = i + 1;
+            while (j < text.length && (text[j] === " " || text[j] === "\t" || text[j] === "\n" || text[j] === "\r")) {
+                j += 1;
+            }
+            if (text[j] === "}" || text[j] === "]") {
+                i += 1;
+                continue;
+            }
+        }
+        out += c;
+        i += 1;
+    }
+    return out;
+}
+export function parseJsonc(text) {
+    return JSON.parse(stripTrailingCommas(stripComments(text)));
+}

package/dist/permissions.d.ts

@@ -0,0 +1,4 @@
+import type { ScopeResult } from "./scope.js";
+export declare function buildExternalDirectory(scope: ScopeResult): Record<string, string>;
+export declare function mergeExternalDirectory(current: unknown, allows: Record<string, string>): Record<string, string>;
+export declare function mergePermission(current: unknown, external: Record<string, string>): unknown;

package/dist/permissions.js

@@ -0,0 +1,36 @@
+import { existsSync } from "node:fs";
+function patternPath(p) {
+    return p.replaceAll("\\", "/") + "/**";
+}
+export function buildExternalDirectory(scope) {
+    const rules = {};
+    for (const wt of scope.config.worktrees) {
+        if (!existsSync(wt.path))
+            continue;
+        rules[patternPath(wt.path)] = "allow";
+        if (wt.realpath !== wt.path)
+            rules[patternPath(wt.realpath)] = "allow";
+    }
+    return rules;
+}
+export function mergeExternalDirectory(current, allows) {
+    if (current && typeof current === "object" && !Array.isArray(current)) {
+        return { ...current, ...allows };
+    }
+    if (typeof current === "string") {
+        return { "*": current, ...allows };
+    }
+    return allows;
+}
+export function mergePermission(current, external) {
+    if (typeof current === "string")
+        return current;
+    if (!current || typeof current !== "object" || Array.isArray(current)) {
+        return { external_directory: external };
+    }
+    const base = current;
+    return {
+        ...base,
+        external_directory: mergeExternalDirectory(base.external_directory, external),
+    };
+}

package/dist/schema.d.ts

@@ -0,0 +1,49 @@
+export declare const WORKSPACE_SCOPE_SCHEMA: {
+    $schema: string;
+    title: string;
+    type: string;
+    additionalProperties: boolean;
+    properties: {
+        name: {
+            type: string;
+            description: string;
+        };
+        workspace: {
+            type: string;
+            additionalProperties: boolean;
+            properties: {
+                path: {
+                    type: string;
+                    description: string;
+                };
+                description: {
+                    type: string;
+                    description: string;
+                };
+            };
+        };
+        worktrees: {
+            type: string;
+            items: {
+                type: string;
+                additionalProperties: boolean;
+                required: string[];
+                properties: {
+                    name: {
+                        type: string;
+                        description: string;
+                    };
+                    path: {
+                        type: string;
+                        description: string;
+                    };
+                    description: {
+                        type: string;
+                        description: string;
+                    };
+                };
+            };
+        };
+    };
+    required: string[];
+};

package/dist/schema.js

@@ -0,0 +1,31 @@
+export const WORKSPACE_SCOPE_SCHEMA = {
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    title: "WorkspaceScopeConfig",
+    type: "object",
+    additionalProperties: false,
+    properties: {
+        name: { type: "string", description: "工作区名称" },
+        workspace: {
+            type: "object",
+            additionalProperties: false,
+            properties: {
+                path: { type: "string", description: "工作区根路径" },
+                description: { type: "string", description: "工作区职责说明" },
+            },
+        },
+        worktrees: {
+            type: "array",
+            items: {
+                type: "object",
+                additionalProperties: false,
+                required: ["name", "path"],
+                properties: {
+                    name: { type: "string", description: "仓库名，如 frontend / backend" },
+                    path: { type: "string", description: "worktree 路径（绝对路径，或相对工作区根目录，如 ../frontend）" },
+                    description: { type: "string", description: "该路径职责说明，会注入 AI 上下文" },
+                },
+            },
+        },
+    },
+    required: ["worktrees"],
+};

package/dist/scope.d.ts

@@ -0,0 +1,22 @@
+export interface WorktreeDef {
+    name: string;
+    path: string;
+    realpath: string;
+    description?: string;
+}
+export interface WorkspaceScope {
+    name: string;
+    workspace: {
+        path: string;
+        description?: string;
+    };
+    worktrees: WorktreeDef[];
+}
+export interface ScopeResult {
+    config: WorkspaceScope;
+    sidecarPath: string;
+    sidecarDir: string;
+}
+export declare function invalidateScope(): void;
+export declare function findSidecarPath(anchor: string): string | null;
+export declare function loadScope(anchor: string): ScopeResult | null;

package/dist/scope.js

@@ -0,0 +1,94 @@
+import { basename, dirname, isAbsolute, join } from "node:path";
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import os from "node:os";
+import { parseJsonc } from "./jsonc.js";
+let cached = null;
+let cachedAnchor = null;
+export function invalidateScope() {
+    cached = null;
+    cachedAnchor = null;
+}
+export function findSidecarPath(anchor) {
+    let dir = anchor;
+    for (let depth = 0; depth < 10; depth += 1) {
+        const candidate = join(dir, ".opencode", "workspace-scope.jsonc");
+        if (existsSync(candidate))
+            return candidate;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+    return null;
+}
+function toAbsolutePath(p, base) {
+    const t = p.trim();
+    if (t.startsWith("~"))
+        return join(os.homedir(), t.slice(1));
+    if (isAbsolute(t))
+        return t;
+    return join(base, t);
+}
+function normalizePath(p) {
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        return p;
+    }
+}
+export function loadScope(anchor) {
+    if (cached && cachedAnchor === anchor)
+        return cached;
+    cached = null;
+    cachedAnchor = anchor;
+    const sidecarPath = findSidecarPath(anchor);
+    if (!sidecarPath)
+        return null;
+    let parsed;
+    try {
+        parsed = parseJsonc(readFileSync(sidecarPath, "utf8"));
+    }
+    catch {
+        return null;
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+        return null;
+    const raw = parsed;
+    if (!Array.isArray(raw.worktrees))
+        return null;
+    const sidecarDir = dirname(sidecarPath);
+    const workspaceRoot = dirname(sidecarDir);
+    const wsRaw = raw.workspace && typeof raw.workspace === "object"
+        ? raw.workspace
+        : {};
+    const workspacePath = normalizePath(typeof wsRaw.path === "string" && wsRaw.path
+        ? toAbsolutePath(wsRaw.path, workspaceRoot)
+        : workspaceRoot);
+    const worktrees = raw.worktrees
+        .filter((w) => !!w && typeof w === "object" && typeof w.name === "string" && typeof w.path === "string")
+        .map((w) => {
+        const path = toAbsolutePath(w.path, workspacePath);
+        return {
+            name: w.name,
+            path,
+            realpath: normalizePath(path),
+            description: typeof w.description === "string" ? w.description : undefined,
+        };
+    });
+    if (worktrees.length === 0)
+        return null;
+    const name = typeof raw.name === "string" && raw.name ? raw.name : basename(anchor);
+    return {
+        config: {
+            name,
+            workspace: {
+                path: workspacePath,
+                description: typeof wsRaw.description === "string" ? wsRaw.description : undefined,
+            },
+            worktrees,
+        },
+        sidecarPath,
+        sidecarDir,
+    };
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "opencode-workspace-scope",
+  "version": "0.1.0",
+  "description": "全局安装、sidecar 自激活的 opencode 插件：按工作区配置自动生成 external_directory 权限，并把工作区 worktree 路径与职责注入 AI 上下文，支撑多 worktree 并行开发互不干扰。",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run typecheck && npm run build"
+  },
+  "keywords": [
+    "opencode",
+    "plugin",
+    "worktree",
+    "workspace",
+    "permission"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@opencode-ai/plugin": "^1.18.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.5.0"
+  }
+}