autosnippet 1.5.7 → 1.5.8

package/README.md

@@ -114,7 +114,7 @@ asd install:full --lancedb # 仅安装 LanceDB（向量检索更快）
 | **Recipe** | `Knowledge/recipes/` 下的 Markdown 知识（配方）：含代码块 + 使用说明，供 AI 检索、Guard、搜索 |
 | **Snippet** | Xcode 代码片段，通过 trigger（默认 `@`）补全，可与 Recipe 关联 |
 | **Candidate（候选）** | 待审核入库的项；来自 `as:create`、MCP 提交、`asd ais` 扫描等，经 Dashboard 审核后保存为 Recipe/Snippet |
-| **Knowledge** | 项目知识库目录，包含 `recipes/`、`.autosnippet/`（索引、candidates、guard 配置等）；Snippet 配置在 root spec 的 list 中 |
+| **Knowledge** | 项目知识库目录，包含 `recipes/`、`.autosnippet/`（索引、candidates、guard 配置等）；Snippet 配置在 root spec 的 list 中。其下各路径与 Git 的关系见 [Knowledge 目录与 Git](#knowledge-目录与-git)。 |
 | **Dashboard** | Web 管理后台（`asd ui` 启动），含 Recipes、Candidates、Guard、Snippets 等页面 |
 | **watch** | 文件监听进程（`asd ui` 或 `asd watch` 启动），保存时触发 `as:create`、`as:guard`、`as:search` |
 | **Guard** | 按 Recipe 知识库对代码做 AI 审查；`// as:guard` 触发 |
@@ -125,7 +125,23 @@ asd install:full --lancedb # 仅安装 LanceDB（向量检索更快）
 | **项目根** | 含 `AutoSnippetRoot.boxspec.json` 的目录 |
 | **Target** | SPM 模块/编译单元；`asd ais <Target>` 扫描该 Target 下的源码提取候选 |
 
-**详细介绍**：启动 `asd ui` 后访问 Dashboard → **使用说明** 页；或参阅 [使用文档](docs/使用文档.md)（含 Skills 一览、AI 配置、闭环详解等）。  
+**详细介绍**：启动 `asd ui` 后访问 Dashboard → **使用说明** 页；或参阅 [使用文档](docs/使用文档.md)（含 Skills 一览、AI 配置、闭环详解等）。
+
+## Knowledge 目录与 Git
+
+Knowledge 下各路径与版本控制的关系建议如下（可按项目需要调整）：
+
+| 路径 | 说明 | 建议 |
+|------|------|------|
+| **Knowledge/recipes/** | Recipe 的 Markdown 文件 | **Git 子仓库**：单独建远程仓库并 `git submodule add <url> Knowledge/recipes`，用于权限拦截（仅能 push 子仓库的人可保存/上传 Recipe）。详见 [权限设置说明](docs/权限设置说明.md) 中「只把 Knowledge/recipes 作为子仓库」。 |
+| **Knowledge/.autosnippet/** | Guard 规则、违反记录、candidates、recipe-stats、context 配置等 | **跟随主仓库 Git**：规则与配置建议提交到主仓库，便于团队共享。 |
+| **Knowledge/.autosnippet/context/index/** | 语义向量索引（embed 生成） | **不跟随 Git**：体积大、机器相关，建议加入 `.gitignore`（如 `Knowledge/.autosnippet/context/index/` 或其下 `lancedb/`、`vector_index.json`）。 |
+| **Knowledge/.autosnippet/candidates/**（若存在） | 候选数据等 | 视需要：若仅本地缓存可不提交；若团队共享可跟随主仓库或单独子仓库。 |
+| **Knowledge/AutoSnippet.spmmap.json**（若存在） | SPM 依赖映射 | **跟随主仓库 Git**：便于依赖关系图一致。 |
+
+- **跟随主仓库 Git**：由主项目 `git add/commit/push` 管理，所有人按主仓库权限读写。
+- **Git 子仓库**：`Knowledge/recipes` 为单独仓库（submodule），Recipe 上传（git push）由 Git 服务端权限拦截。配合 `.env` 中 `ASD_RECIPES_WRITE_DIR=Knowledge/recipes` 是为了保证管理员（有 push 权限者）能够正确提交 Recipe：探针目录与 Recipe 写入目录一致，保存后可正常推送。
+- **不跟随 Git**：在 `.gitignore` 中忽略，不提交、不推送。
 
 ---
 

package/bin/asd

@@ -13,6 +13,7 @@ DIR="$(cd "$(dirname "$SCRIPT")" && pwd)"
 # 将调用时的当前目录传给 Node，供查找项目根（dev:link 等场景下 process.cwd() 可能不是用户所在目录）
 ASD_CWD="$(pwd)"
 export ASD_CWD
+# 优先 Swift 入口（完整性校验，仅 macOS），否则回退 node
 if [ -x "$DIR/asd-verify" ]; then
 	exec "$DIR/asd-verify" "$@"
 else

package/bin/asnip.js

@@ -22,6 +22,21 @@
 
 const fs = require('fs');
 const path = require('path');
+
+// 入口校验：包内存在 checksums.json 且未经过 asd-verify（无 ASD_VERIFIED）时，可拒跑或警告，避免绕过完整性校验直接运行 node bin/asnip.js
+const pkgRoot = path.join(__dirname, '..');
+const checksumsPath = path.join(pkgRoot, 'checksums.json');
+if (fs.existsSync(checksumsPath) && process.env.ASD_VERIFIED !== '1') {
+	const msg = 'asd: 未经过完整性校验入口（请使用 asd 命令，勿直接运行 node bin/asnip.js）。开发/调试可设 ASD_SKIP_ENTRY_CHECK=1 跳过。';
+	if (process.env.ASD_STRICT_ENTRY === '1') {
+		console.error(msg);
+		process.exit(1);
+	}
+	if (process.env.ASD_SKIP_ENTRY_CHECK !== '1') {
+		console.warn('⚠️  ' + msg);
+	}
+}
+
 // 读取输入命令
 const inquirer = require('inquirer');
 // 命令行工具
@@ -1023,6 +1038,17 @@ commander
 			console.log(`${fail} .env: 不存在，请从 .env.example 复制并填写 API Key`);
 		}
 
+		// 2.5 写权限探针（可选）
+		try {
+			const writeGuard = require('../lib/writeGuard');
+			const probeDir = writeGuard.getProbeDir(projectRoot);
+			if (probeDir) {
+				const probePath = path.join(projectRoot, probeDir);
+				const exists = fs.existsSync(probePath) && fs.statSync(probePath).isDirectory();
+				console.log(`${exists ? ok : fail} 写权限探针: 已配置 (${probeDir})${exists ? '' : '，目录不存在'}`);
+			}
+		} catch (_) {}
+
 		// 3. 语义索引（JsonAdapter: context/index/vector_index.json，LanceDB: context/index/lancedb/，manifest 由 embed 写入）
 		const paths = require('../lib/infra/paths');
 		const indexPath = paths.getContextIndexPath(projectRoot);

package/checksums.json

@@ -1,5 +1,5 @@
 {
-  "bin/asnip.js": "39b8cb4e8c8db37230d95dc234178b2c921d129f5c6ba4a671541de2781d35cd",
+  "bin/asnip.js": "9c8fdca74a0522836c48a61a85db65b065dc8f72e026696040d280d6714edeb9",
   "bin/ui.js": "e1b52cb75b6d404edcb9298f6e3dcae0bf7e2bd95c7df2c38ff020c8111bf96f",
   "lib/writeGuard.js": "f6574f09668d854b871415e96570359859b0ecd79d46d609af90b2d2833bd817"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "autosnippet",
-	"version": "1.5.7",
+	"version": "1.5.8",
 	"description": "A iOS module management tool.",
 	"main": "index.js",
 	"scripts": {

package/resources/asd-entry/main.swift

@@ -1,6 +1,8 @@
-/**
- * AutoSnippet 原生入口：完整性校验 + spawn Node 执行 bin/asnip.js
- * 若 checksums.json 不存在则跳过校验（开发模式）；存在则校验关键文件 SHA-256，不通过则 exit(1)。
+#!/usr/bin/env swift
+/*
+ * AutoSnippet 完整性校验入口（Swift，仅 macOS）
+ * 读 checksums.json，校验关键文件 SHA-256，通过则设置 ASD_VERIFIED=1 并 spawn node bin/asnip.js。
+ * 构建：node scripts/build-asd-entry.js，产物 bin/asd-verify。
  */
 
 import Foundation
@@ -8,66 +10,58 @@ import CryptoKit
 
 func fail(_ msg: String) -> Never {
 	fputs(msg + "\n", stderr)
-	fflush(stderr)
 	exit(1)
 }
 
-/// 从 argv[0] 解析包根目录（bin 的父目录）。要求 root 下存在 bin/asnip.js，否则返回 nil。
+/// 从可执行路径解析包根目录（bin/asd-verify 的上级的上级）
 func getPackageRoot() -> String? {
-	let arg0 = CommandLine.arguments[0]
-	let cwd = FileManager.default.currentDirectoryPath
-	var pathStr = arg0
-	if !arg0.hasPrefix("/") {
-		pathStr = (cwd as NSString).appendingPathComponent(arg0)
+	let argv0 = CommandLine.arguments[0]
+	let path = (argv0 as NSString).standardizingPath
+	var url = URL(fileURLWithPath: path)
+	if path != (path as NSString).resolvingSymlinksInPath {
+		url = URL(fileURLWithPath: (path as NSString).resolvingSymlinksInPath)
 	}
-	let url = URL(fileURLWithPath: pathStr).resolvingSymlinksInPath()
-	let binDir = url.deletingLastPathComponent()
-	let root = binDir.deletingLastPathComponent()
-	let rootPath = root.path
-	let asnipPath = (rootPath as NSString).appendingPathComponent("bin/asnip.js")
-	guard FileManager.default.fileExists(atPath: asnipPath) else {
-		return nil
-	}
-	return rootPath
+	var dir = url.deletingLastPathComponent().path  // bin
+	dir = (dir as NSString).deletingLastPathComponent  // package root
+	return dir
 }
 
-/// 计算文件 SHA-256 十六进制字符串
-func sha256Hex(fileURL: URL) -> String? {
-	guard let data = try? Data(contentsOf: fileURL) else { return nil }
-	let digest = SHA256.hash(data: data)
-	return digest.map { String(format: "%02x", $0) }.joined()
+/// 文件内容 SHA-256 小写 hex
+func sha256Hex(filePath: String) -> String? {
+	guard let data = try? Data(contentsOf: URL(fileURLWithPath: filePath)) else { return nil }
+	let hash = SHA256.hash(data: data)
+	return hash.map { String(format: "%02x", $0) }.joined()
 }
 
-/// 校验 checksums.json 中列出的文件。禁止 relPath 含 ".." 或为绝对路径，防止路径逃逸。
+/// 校验 checksums.json 中列出的文件。拒绝 relPath 含 ".." 或为绝对路径。
 func verifyIntegrity(root: String, checksumsPath: String) -> Bool {
 	guard let data = try? Data(contentsOf: URL(fileURLWithPath: checksumsPath)) else {
 		fputs("asd: 无法读取 checksums.json\n", stderr)
 		return false
 	}
-	guard let json = try? JSONSerialization.jsonObject(with: data) as? [String: String] else {
+	guard let json = try? JSONSerialization.jsonObject(with: data),
+	      let entries = json as? [String: String] else {
 		fputs("asd: checksums.json 格式无效\n", stderr)
 		return false
 	}
-	let rootURL = URL(fileURLWithPath: root)
-	var rootNorm = rootURL.resolvingSymlinksInPath().path
-	if rootNorm.hasSuffix("/") { rootNorm = String(rootNorm.dropLast()) }
-	for (relPath, expectedHex) in json {
+	let rootNorm = (root as NSString).standardizingPath
+	for (relPath, expectedHex) in entries {
 		if relPath.hasPrefix("/") || relPath.contains("..") {
 			fputs("asd: 校验拒绝非法路径: \(relPath)\n", stderr)
 			return false
 		}
-		let fileURL = rootURL.appendingPathComponent(relPath)
-		let resolvedPath = fileURL.resolvingSymlinksInPath().path
-		guard resolvedPath == rootNorm || resolvedPath.hasPrefix(rootNorm + "/") else {
+		let fullPath = (root as NSString).appendingPathComponent(relPath)
+		let fullNorm = (fullPath as NSString).standardizingPath
+		let rootSlash = rootNorm.hasSuffix("/") ? rootNorm : rootNorm + "/"
+		guard fullNorm == rootNorm || fullNorm.hasPrefix(rootSlash) else {
 			fputs("asd: 校验拒绝路径逃逸: \(relPath)\n", stderr)
 			return false
 		}
-		guard FileManager.default.fileExists(atPath: fileURL.path),
-		      let actualHex = sha256Hex(fileURL: fileURL) else {
-			fputs("asd: 校验失败（无法读取）: \(relPath)\n", stderr)
+		guard let actualHex = sha256Hex(filePath: fullPath) else {
+			fputs("asd: 完整性校验失败: \(relPath)\n", stderr)
 			return false
 		}
-		if actualHex != expectedHex {
+		if actualHex.lowercased() != expectedHex.lowercased() {
 			fputs("asd: 完整性校验失败: \(relPath)\n", stderr)
 			return false
 		}
@@ -75,19 +69,22 @@ func verifyIntegrity(root: String, checksumsPath: String) -> Bool {
 	return true
 }
 
-/// 执行 node bin/asnip.js [args...]，返回子进程退出码。将调用时的 cwd 传入 ASD_CWD，供 asnip 查找项目根。
-func spawnNode(root: String) -> Int32 {
+/// 执行 node bin/asnip.js [args...]，将调用时的 cwd 传入 ASD_CWD，校验通过则设 ASD_VERIFIED=1。
+func spawnNode(root: String, integrityVerified: Bool) -> Int32 {
 	let asnipPath = (root as NSString).appendingPathComponent("bin/asnip.js")
 	guard FileManager.default.fileExists(atPath: asnipPath) else {
 		fail("asd: 未找到 bin/asnip.js")
 	}
-	let nodeArgs = ["node", asnipPath] + CommandLine.arguments.dropFirst()
+	let nodeArgs = ["node", asnipPath] + Array(CommandLine.arguments.dropFirst())
 	let process = Process()
 	process.executableURL = URL(fileURLWithPath: "/usr/bin/env")
-	process.arguments = Array(nodeArgs)
+	process.arguments = nodeArgs
 	process.currentDirectoryURL = URL(fileURLWithPath: root)
 	var env = ProcessInfo.processInfo.environment
 	env["ASD_CWD"] = FileManager.default.currentDirectoryPath
+	if integrityVerified {
+		env["ASD_VERIFIED"] = "1"
+	}
 	process.environment = env
 	process.standardInput = FileHandle.standardInput
 	process.standardOutput = FileHandle.standardOutput
@@ -108,11 +105,12 @@ guard let root = getPackageRoot() else {
 }
 
 let checksumsPath = (root as NSString).appendingPathComponent("checksums.json")
-
+var integrityVerified = false
 if FileManager.default.fileExists(atPath: checksumsPath) {
 	if !verifyIntegrity(root: root, checksumsPath: checksumsPath) {
 		exit(1)
 	}
+	integrityVerified = true
 }
 
-exit(spawnNode(root: root))
+exit(spawnNode(root: root, integrityVerified: integrityVerified))

package/scripts/build-asd-entry.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 
 /**
- * 构建 asd 原生入口（完整性校验 + spawn Node）。仅 macOS 且 Swift 可用时构建，失败则静默跳过。
- * 产物：bin/asd-verify。若不存在，bin/asd 脚本会回退到 node bin/asnip.js。
+ * 构建 asd 完整性校验入口（Swift，仅 macOS）。产物：bin/asd-verify。
+ * 若不存在或构建失败，bin/asd 将回退到 node bin/asnip.js。
  */
 
 if (process.platform !== 'darwin') process.exit(0);