Skip to content

Spot it. Save it. Free, local-first Chrome extension for images, videos and prompts. Explore 2,000+ curated cases and connect your library to AI Agents via MCP. 提示词导演

Keep local Agent guidance private and expand public source checks

MigenAI1eecc63001b5
diff --git a/.gitignore b/.gitignore
index a98d623..2701fb0 100644
--- a/.gitignore
+++ b/.gitignore
@@ -16,6 +16,8 @@ __pycache__/
.local-imports/
.scratch/
.omx/
+AGENTS.override.md
+.learnings/
store/screenshots/*
!store/screenshots/01-library-1280x800.png
!store/screenshots/02-skills-1280x800.png
diff --git a/AGENTS.md b/AGENTS.md
index 85eef0d..dd57b33 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -4,13 +4,13 @@ PromptDirector 是本地优先的视觉创作灵感库,服务用户保存、
## 开始与接续
-每次新对话及上下文压缩恢复后,必须读取本文件。维护者工作区存在时,继续读取同级 [Private 开发入口](../PromptDirector-Private/AGENTS.md),按其必读顺序恢复项目、偏好和当前规划,再开始实质工作。
+每次新对话及上下文压缩恢复后,必须读取本文件,并按当前任务阅读 [开发说明](docs/DEVELOPMENT.md)、相关源码和测试。
-若私有工作区不可访问,明确说明无法恢复维护者上下文;公开贡献以当前请求、README、相关源码和测试为依据,不能宣称已经读取私人规划。
+以当前请求、README、相关源码和测试为依据;未读取或未验证的内容不能当作事实。
## 开发与交付
- 修改前核对实时 Git 状态,保护已有改动;沿完整用户任务追踪共用规则和消费者。
- 案例、原件、用户编辑与组织关系的延续性优先。质量、能力、权限和费用取舍需透明说明。
- 运行与变更相关的验证;代码完成、自动验证、安装验收、发布验证分别说明。
-- 维护者原话、规划、研究、复盘和验证回执按 Private 文档规范写回;本仓库保留面向公开使用者的内容。
+- 本仓库只保留产品源码、测试和公开使用说明;提交前运行 `npm run check:public`,不提交个人资料、本机路径或凭据。
diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md
index 96edd6c..a8e6d50 100644
--- a/docs/DEVELOPMENT.md
+++ b/docs/DEVELOPMENT.md
@@ -21,6 +21,8 @@ Load `extension/` in Chrome or Edge for source development, or extract the gener
Published ZIPs keep a top-level `manifest.json`. Source organization does not change the installation layout or the existing local upgrade path.
+Keep personal Agent instructions in the Git-ignored `AGENTS.override.md`. Codex reads that file in place of `AGENTS.md`, so have it read the public `AGENTS.md` before adding local guidance. Run `npm run check:public` before committing; it checks publishable text files, including hidden workflows and new files. It does not audit Git history or the visible contents of images.
+
## Checks and packaging
`npm run verify` runs source checks, historical data compatibility, packaged Chromium journeys and an upgrade rehearsal using a previous release. `npm run check:compat` checks the supported data formats. `npm run package:release` builds the Store upload variant. These commands do not publish a release or upload to the Store.
diff --git a/test/curated-skill-package.test.js b/test/curated-skill-package.test.js
index 5ce2641..d25a172 100644
--- a/test/curated-skill-package.test.js
+++ b/test/curated-skill-package.test.js
@@ -20,7 +20,7 @@ function fixture(overrides = {}) {
description: "把主体层级组织成清晰画面。",
skillMarkdown: "# 构图方法\n\n保持主体清晰。",
references: [{ path: "references/guide.md", markdown: "# Guide\n\nUse depth.", runtime: true }],
- provenanceMarkdown: "# 私人来源\n\n/Users/private/cases.md"
+ provenanceMarkdown: `# 私人来源\n\n${["", "Users", "private", "cases.md"].join("/")}`
}, { id: "local:one", versionId: "version:one", now: "2026-08-23T00:00:00.000Z" }).skill;
}
@@ -47,7 +47,7 @@ test("curated submission snapshot includes a byte-verified image, is exact-previ
test("privacy findings are reported without mutating the final preview", async () => {
const skill = fixture();
- skill.versions[0].skillMarkdown = "# Method\n\nAPI_KEY=\"secret-value-123456\", /Users/alice/private.md, [email protected]";
+ skill.versions[0].skillMarkdown = `# Method\n\nAPI_KEY="secret-value-123456", ${["", "Users", "alice", "private.md"].join("/")}, [email protected]`;
const snapshot = await buildCuratedSkillSnapshot(skill, {
author: "Creator One",
summary: "A reusable composition method.",
diff --git a/test/import-staging.test.js b/test/import-staging.test.js
index 258adf4..1d92905 100644
--- a/test/import-staging.test.js
+++ b/test/import-staging.test.js
@@ -26,7 +26,7 @@ test("import staging persists only resumable metadata and safe relative paths",
formatCategory: "image",
posterAssetId: "poster:one",
duplicateAssetId: "existing:one",
- absolutePath: "/Users/private/frame.png",
+ absolutePath: ["", "Users", "private", "frame.png"].join("/"),
file: { private: true }
});
@@ -45,7 +45,7 @@ test("import staging persists only resumable metadata and safe relative paths",
posterAssetId: "poster:one",
duplicateAssetId: "existing:one"
});
- assert.equal(JSON.stringify(result.state).includes("/Users/private"), false);
+ assert.equal(JSON.stringify(result.state).includes(["", "Users", "private"].join("/")), false);
});
test("staging preserves audio and inert linked attachment boundaries", () => {
@@ -88,7 +88,7 @@ test("staging preserves unsupported local links without pretending their source
forceAllowed: false
},
handle: { kind: "file", getFile() {} },
- absolutePath: "/Users/private/custom.zzz"
+ absolutePath: ["", "Users", "private", "custom.zzz"].join("/")
}] });
assert.equal(state.assets.length, 1);
@@ -99,7 +99,7 @@ test("staging preserves unsupported local links without pretending their source
assert.equal(state.assets[0].sourceLastModified, 1_776_500_123_000);
assert.equal(Object.hasOwn(state.assets[0], "contentHash"), false);
assert.equal(Object.hasOwn(state.assets[0], "handle"), false);
- assert.equal(JSON.stringify(state).includes("/Users/private"), false);
+ assert.equal(JSON.stringify(state).includes(["", "Users", "private"].join("/")), false);
});
test("unsupported local link moves from staging to a case media record without a blob fingerprint", () => {
diff --git a/test/local-media.test.js b/test/local-media.test.js
index 906dc61..86bcd88 100644
--- a/test/local-media.test.js
+++ b/test/local-media.test.js
@@ -37,7 +37,7 @@ test("local media detection keeps only supported formats and safe relative paths
return true;
});
assert.equal(normalizeLocalRelativePath("folder/reference/frame.gif", "frame.gif"), "folder/reference/frame.gif");
- assert.throws(() => normalizeLocalRelativePath("/Users/private/frame.gif", "frame.gif"), /相对路径/);
+ assert.throws(() => normalizeLocalRelativePath(["", "Users", "private", "frame.gif"].join("/"), "frame.gif"), /相对路径/);
assert.throws(() => normalizeLocalRelativePath("../private/frame.gif", "frame.gif"), /相对路径/);
});
diff --git a/test/public-source-boundary.test.js b/test/public-source-boundary.test.js
index ef57ca4..2012c29 100644
--- a/test/public-source-boundary.test.js
+++ b/test/public-source-boundary.test.js
@@ -1,16 +1,25 @@
import test from "node:test";
import assert from "node:assert/strict";
-import { mkdtemp, mkdir, copyFile, writeFile, rm } from "node:fs/promises";
+import { mkdtemp, mkdir, copyFile, writeFile, rm, symlink } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { spawnSync } from "node:child_process";
-async function checkMarkdown(content, privateDirectory) {
+async function checkFiles(files, { privateDirectory, git = false, ignore = [], tracked = [], links = {} } = {}) {
const root = await mkdtemp(join(tmpdir(), "public-source-boundary-"));
try {
await mkdir(join(root, "tools"));
await copyFile(new URL("../tools/validate-public-source.mjs", import.meta.url), join(root, "tools", "validate-public-source.mjs"));
- await writeFile(join(root, "README.md"), content);
+ for (const [path, content] of Object.entries(files)) {
+ await mkdir(join(root, path, ".."), { recursive: true });
+ await writeFile(join(root, path), content);
+ }
+ for (const [path, target] of Object.entries(links)) await symlink(target, join(root, path));
+ if (git) {
+ assert.equal(spawnSync("git", ["init", root]).status, 0);
+ if (ignore.length) await writeFile(join(root, ".gitignore"), `${ignore.join("\n")}\n`);
+ for (const path of tracked) assert.equal(spawnSync("git", ["-C", root, "add", "--force", path]).status, 0);
+ }
if (privateDirectory) {
await mkdir(join(root, privateDirectory));
await writeFile(join(root, privateDirectory, 'LEARNINGS.md'), 'Private feedback without any machine path');
@@ -22,28 +31,110 @@ async function checkMarkdown(content, privateDirectory) {
}
test("public documentation rejects machine-specific macOS screenshot paths", async () => {
- for (const prefix of ["/private/var/folders/", "/var/folders/"]) {
- const result = await checkMarkdown(`Screenshot: ${prefix}example/T/capture.png`);
+ for (const prefix of [["", "private", "var", "folders", ""].join("/"), ["", "var", "folders", ""].join("/")]) {
+ const result = await checkFiles({ "README.md": `Screenshot: ${prefix}example/T/capture.png` });
assert.notEqual(result.status, 0);
assert.match(result.stderr, /公开文档包含维护者本机路径/);
}
});
test("public documentation rejects local home and temporary workspace paths", async () => {
- for (const path of ["/Users/example/project/notes.md", "/private/tmp/example/report.md"]) {
- const result = await checkMarkdown(path);
+ for (const path of [["", "Users", "example", "project", "notes.md"].join("/"), ["", "private", "tmp", "example", "report.md"].join("/")]) {
+ const result = await checkFiles({ "README.md": path });
assert.notEqual(result.status, 0);
assert.match(result.stderr, /公开文档包含维护者本机路径/);
}
});
test("public documentation accepts portable instructions and repository links", async () => {
- const result = await checkMarkdown("See [guide](docs/guide.md). Write local output to <local-temp>/capture.png.");
+ const result = await checkFiles({ "README.md": "See [guide](docs/guide.md). Write local output to <local-temp>/capture.png." });
assert.equal(result.status, 0, result.stderr);
});
test('public source rejects private learning records even without local paths or credentials', async () => {
- const result = await checkMarkdown('Public README', '.learnings');
+ const result = await checkFiles({ 'README.md': 'Public README' }, { privateDirectory: '.learnings' });
assert.notEqual(result.status, 0);
assert.match(result.stderr, /公开源码树包含内部工作目录:\.learnings/);
});
+
+test("private sibling references fail in source, documentation and hidden workflows", async () => {
+ const privateName = ["Example", "Private"].join("-");
+ for (const path of ["AGENTS.md", "connector/config.mjs", ".github/workflows/check.yml"]) {
+ const result = await checkFiles({ [path]: `Read ../${privateName}/AGENTS.md` });
+ assert.notEqual(result.status, 0, path);
+ assert.match(result.stderr, /公开源码包含私人工作区引用/);
+ }
+});
+
+test("machine paths fail outside Markdown on every supported OS", async () => {
+ const paths = [
+ ["", "home", "example", "project", "file"].join("/"),
+ ["", "Volumes", "example", "library", "file"].join("/"),
+ ["C:", "Users", "example", "project", "file"].join("\\"),
+ ["C:", "Users", "example", "project", "file"].join("\\\\")
+ ];
+ for (const path of paths) {
+ const result = await checkFiles({ "tools/config.json": JSON.stringify({ path }) });
+ assert.notEqual(result.status, 0, path);
+ assert.match(result.stderr, /本机路径/);
+ }
+});
+
+test("credential findings identify the file without printing the secret", async () => {
+ const secret = ["ghp", "x".repeat(36)].join("_");
+ const result = await checkFiles({ "config.json": JSON.stringify({ token: secret }) });
+ assert.notEqual(result.status, 0);
+ assert.match(result.stderr, /疑似凭据:config.json:1/);
+ assert.equal(result.stderr.includes(secret), false);
+});
+
+test("ignored local instructions stay private and a force-added override cannot pass", async () => {
+ const files = { "README.md": "Public source", "AGENTS.override.md": `Read ../${["Example", "Private"].join("-")}/AGENTS.md` };
+ const options = { git: true, ignore: ["AGENTS.override.md"] };
+ const ignored = await checkFiles(files, options);
+ assert.equal(ignored.status, 0, ignored.stderr);
+ const tracked = await checkFiles(files, { ...options, tracked: ["AGENTS.override.md"] });
+ assert.notEqual(tracked.status, 0);
+ assert.match(tracked.stderr, /本地配置文件:AGENTS.override.md/);
+});
+
+test("ignored local assets are preserved while tracked private records are rejected", async () => {
+ const files = { "README.md": "Public source", ".local-imports/cases.json": "Local assets" };
+ const options = { git: true, ignore: [".local-imports/"] };
+ const ignored = await checkFiles(files, options);
+ assert.equal(ignored.status, 0, ignored.stderr);
+ const tracked = await checkFiles(files, { ...options, tracked: [".local-imports/cases.json"] });
+ assert.notEqual(tracked.status, 0);
+ assert.match(tracked.stderr, /内部工作目录/);
+});
+
+test("untracked publishable files are checked and environment files are blocked", async () => {
+ const result = await checkFiles({ ".env": "TOKEN=local", "README.md": "Public source" }, { git: true });
+ assert.notEqual(result.status, 0);
+ assert.match(result.stderr, /本地配置文件:\.env/);
+ const example = await checkFiles({ ".env.example": "TOKEN=<your-token>" }, { git: true });
+ assert.equal(example.status, 0, example.stderr);
+});
+
+test("public service URLs, synthetic identifiers and binary assets remain publishable", async () => {
+ const result = await checkFiles({
+ "source.js": "const id = 'project-private'; const url = 'https://github.com/example/product';",
+ "image.png": new Uint8Array([0, 255, 1, 2]),
+ ".github/workflows/check.yml": "name: checks"
+ });
+ assert.equal(result.status, 0, result.stderr);
+});
+
+test("a published symlink exposes its private target even when that target cannot be read", async () => {
+ const result = await checkFiles({ "README.md": "Public source" }, {
+ git: true,
+ tracked: ["notes.md"],
+ links: { "notes.md": ["", "Users", "example", "private", "missing.md"].join("/") }
+ });
+ assert.notEqual(result.status, 0, "The Git link text is public even though the external file is absent");
+ assert.match(result.stderr, /本机路径:notes.md:1/);
+ const portable = await checkFiles({ "README.md": "Public source" }, {
+ git: true, tracked: ["guide.md"], links: { "guide.md": "README.md" }
+ });
+ assert.equal(portable.status, 0, portable.stderr);
+});
diff --git a/tools/validate-public-source.mjs b/tools/validate-public-source.mjs
index 74d8bdd..6d501b3 100644
--- a/tools/validate-public-source.mjs
+++ b/tools/validate-public-source.mjs
@@ -1,6 +1,7 @@
-import { access, readFile, readdir } from "node:fs/promises";
-import { extname, join, relative } from "node:path";
+import { lstat, readFile, readlink, readdir } from "node:fs/promises";
+import { join, relative } from "node:path";
import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
const projectRoot = fileURLToPath(new URL("../", import.meta.url));
const privateWorkspaceDirectories = [
@@ -17,52 +18,64 @@ const privateWorkspaceDirectories = [
const privateWorkspaceFiles = ["CONTEXT.md", "context.md", "docs/DESIGN.md", "test/LOCAL_EXTENSION_LAB.md", "store/CHROME_WEB_STORE_SUBMISSION.md"];
-const presentPrivateDirectories = [];
-for (const path of privateWorkspaceDirectories) {
- if (await exists(join(projectRoot, path))) presentPrivateDirectories.push(path);
-}
-if (presentPrivateDirectories.length) {
- throw new Error(`公开源码树包含内部工作目录:${presentPrivateDirectories.join(", ")}`);
-}
-
-const presentPrivateFiles = [];
-for (const path of privateWorkspaceFiles) {
- if (await exists(join(projectRoot, path))) presentPrivateFiles.push(path);
-}
-if (presentPrivateFiles.length) {
- throw new Error(`公开源码树包含内部上下文文件:${presentPrivateFiles.join(", ")}`);
-}
-
-const markdownFiles = await collectMarkdown(projectRoot);
-const localPathPattern = /\/Users\/(?!<[^>]+>)[^/\s`]+\/|\/private\/tmp\/|\/(?:private\/)?var\/folders\//;
-const leakedPaths = [];
-for (const file of markdownFiles) {
- const text = await readFile(file, "utf8");
- if (localPathPattern.test(text)) leakedPaths.push(relative(projectRoot, file));
-}
-if (leakedPaths.length) {
- throw new Error(`公开文档包含维护者本机路径:${leakedPaths.join(", ")}`);
-}
-
-process.stdout.write(`${markdownFiles.length} 个公开 Markdown 文件边界检查通过\n`);
-
-async function exists(path) {
+// Use Git's publication boundary, including dotfiles and new, non-ignored files.
+// An ignored local override is allowed; a force-added override is rejected.
+const git = spawnSync("git", ["-C", projectRoot, "ls-files", "--cached", "--others", "--exclude-standard", "-z"], { encoding: "utf8" });
+const sourceFiles = git.status === 0
+ ? [...new Set(git.stdout.split("\0").filter(Boolean))].map((path) => join(projectRoot, path))
+ : await collectFiles(projectRoot);
+const patterns = [
+ ["公开文档包含维护者本机路径", /\/(?:Users|home)\/(?!<[^>]+>)[^/\s`"']+\/|\/Volumes\/(?!<[^>]+>)[^/\s`"']+\/|\/private\/tmp\/|\/(?:private\/)?var\/folders\/|\b[A-Za-z]:[\\/]+Users[\\/]+(?!<[^>]+>)[^\\/\s`"']+[\\/]+/i],
+ ["公开源码包含私人工作区引用", /\b[A-Za-z0-9_.]+-Private\b|(?:\.\.\/|\.\.\\)(?:\.scratch|\.learnings)(?:[\\/]|\b)/],
+ ["公开源码包含疑似凭据", /\bgh[pousr]_[A-Za-z0-9]{30,}\b|\bgithub_pat_[A-Za-z0-9_]{50,}\b|\bsk-(?:proj-)?[A-Za-z0-9_-]{40,}\b|-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----/]
+];
+const findings = [];
+let textFileCount = 0;
+for (const file of sourceFiles) {
+ const path = relative(projectRoot, file).replaceAll("\\", "/");
+ if (privateWorkspaceDirectories.some((directory) => path.startsWith(`${directory.replaceAll("\\", "/")}/`))) {
+ findings.push(`公开源码树包含内部工作目录:${path}`);
+ }
+ if (privateWorkspaceFiles.includes(path)) findings.push(`公开源码树包含内部上下文文件:${path}`);
+ if (path.split("/").includes("AGENTS.override.md") || /(?:^|\/)\.env(?:\.|$)/.test(path) && !path.endsWith(".env.example")) {
+ findings.push(`公开源码包含本地配置文件:${path}`);
+ }
+ let metadata;
try {
- await access(path);
- return true;
+ metadata = await lstat(file);
+ } catch (error) {
+ if (error.code === "ENOENT") continue; // A tracked deletion has no publishable bytes.
+ throw error;
+ }
+ // Git publishes a symlink's target text, never the external file's contents.
+ // Reading errors must fail verification rather than silently skip a file.
+ const bytes = metadata.isSymbolicLink() ? Buffer.from(await readlink(file), "utf8") : await readFile(file);
+ if (bytes.includes(0)) continue;
+ let text;
+ try {
+ text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
} catch {
- return false;
+ continue; // Images and other binary assets need separate visual review.
+ }
+ textFileCount += 1;
+ for (const [label, pattern] of patterns) {
+ const match = pattern.exec(text);
+ if (match) findings.push(`${label}:${path}:${text.slice(0, match.index).split("\n").length}`);
}
}
+if (findings.length) throw new Error(findings.join("\n"));
+
+process.stdout.write(`${textFileCount} 个公开文本文件边界检查通过\n`);
-async function collectMarkdown(directory) {
- const ignored = new Set(["dist", "node_modules", "vendor"]);
+async function collectFiles(directory) {
+ // Standalone fixture directories have no Git index or ignore rules.
+ const ignored = new Set([".git", "dist", "node_modules", "coverage"]);
const files = [];
for (const entry of await readdir(directory, { withFileTypes: true })) {
- if (entry.name.startsWith(".") || ignored.has(entry.name)) continue;
+ if (ignored.has(entry.name)) continue;
const path = join(directory, entry.name);
- if (entry.isDirectory()) files.push(...await collectMarkdown(path));
- else if (entry.isFile() && extname(entry.name) === ".md") files.push(path);
+ if (entry.isDirectory()) files.push(...await collectFiles(path));
+ else if (entry.isFile() || entry.isSymbolicLink()) files.push(path);
}
return files;
}