pi-tsgw 0.0.17 → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -7,6 +7,22 @@
7
7
  本项目不包含私有 API 密钥或网关端点。静态目录包含模型元数据和公开价格估算;
8
8
  这些价格并非你的网关计费费率。
9
9
 
10
+ ## 项目结构
11
+
12
+ 包清单的 `pi.extensions` 指向根 `./index.ts`,作为约 15 行的总入口;provider 注册与生命周期位于 `extensions/provider/`,模型模块位于 `extensions/models/`。搜索模块及相邻测试位于 `extensions/search/`,提示词由 `extensions/prompts.ts` 的 `registerPrompts` 统一注册,正文位于 `prompts/`。宿主集成总测试为根 `index.test.ts`;provider 和搜索测试与对应模块相邻,共享测试夹具仍位于 `extensions/`。技能及其测试路径保持在 `skills/` 和 `extensions/`。
13
+
14
+ ```text
15
+ index.ts # 包总入口
16
+ index.test.ts # 宿主集成总测试
17
+ extensions/provider/ # provider 注册、配置、状态及其测试
18
+ extensions/models/ # 模型目录、策略与联网支持
19
+ extensions/search/ # 搜索注册、代理与相邻测试
20
+ extensions/prompts.ts # registerPrompts
21
+ prompts/memory.ts # 记忆提示词正文
22
+ extensions/upload/ # 本地上传及安全说明
23
+ skills/ # 随包技能
24
+ ```
25
+
10
26
  ## 安装
11
27
 
12
28
  ```bash
@@ -174,6 +190,7 @@ Pi Web 可能要等会话运行时启动后才显示扩展状态。
174
190
  | [tsgw-github](skills/tsgw-github/SKILL.md) | 使用 gh 查询与维护 issue、PR、CI,安全发布正文并核验 Actions 升级。 |
175
191
  | [tsgw-mk-docs](skills/tsgw-mk-docs/SKILL.md) | 需求、设计、执行计划、术语和状态证据的文档治理,含参考清单与模板,不依赖审阅插件。 |
176
192
  | [tsgw-programmer-go](skills/tsgw-programmer-go/SKILL.md) | Go 编码与审查;自产 JSON 使用 PascalCase、零值省略优先 omitzero,真实变更中同步迁移相关旧标签。 |
193
+ | [tsgw-smemo](skills/tsgw-smemo/SKILL.md) | Blinko 共享知识的检索、沉淀与维护,含原有维护授权和操作参考。 |
177
194
 
178
195
  技能从本地维护的工作流整理并适配 Pi,按本项目 MIT 许可证提供;不包含第三方 gitmoji 数据集。
179
196
  项目规则和用户授权优先,不安装 Git hook,不自动推送或发布。已有同类用户级技能时,建议择一启用,避免重复指导。
@@ -190,12 +207,23 @@ GLM 指导使用 5.3,并以 Flash 和 FlashX 为备选。思考级别使用 Pi
190
207
  与其其他非 off 级别一样,映射为 adaptive。
191
208
 
192
209
  安装并执行 `/reload` 后,Pi 会通过包清单发现随包技能,除非宿主/包设置禁用或过滤了技能。
193
- 可以使用 `/skill:tsgw-git-commit` 等命令显式加载;仅加载 `extensions/index.ts` 不会加载包内技能。
210
+ 可以使用 `/skill:tsgw-git-commit` 等命令显式加载;仅加载根 `index.ts` 不会加载包内技能。
194
211
  包设置中的 `skills: []` 可禁用全部技能,`skills: ["skills/tsgw-git-commit"]` 可仅加载指定技能,
195
212
  或用 `skills: ["!skills/tsgw-git-commit/**"]` 排除该技能;由宿主处理,不是 `tsgw` 配置项。
196
213
 
197
214
  只有模型选型技能需要宿主提供支持模型选择的子代理工具及可用的 `tsgw` 模型;通用开发技能不绑定模型 provider。
198
- 本包不提供子代理工具,也不改变调度设置、用户规则或权限。
215
+ 本包不提供子代理工具,也不改变调度设置、用户规则文件或宿主权限。
216
+
217
+ ### 记忆规则注入
218
+
219
+ 常驻提示词正文集中在 `prompts/`,与扩展注册入口分开维护。提示词由 `extensions/prompts.ts` 的
220
+ `registerPrompts` 统一注册;记忆提示词正文位于 `prompts/memory.ts`。
221
+
222
+ 插件在 `before_agent_start` 中注入原用户规则中的记忆体系与既有条目维护授权,
223
+ 不绑定当前模型 provider,不新增配置,不改写用户规则文件。
224
+ 详细流程保留在 `tsgw-smemo` 技能及其参考资料中;`ctx_memory` 仍称为“系统记忆”,
225
+ smemo/Blinko 仍称为“记忆系统”。技能迁移不操作 Blinko 数据或改变宿主认证与权限。
226
+ 从本地 `smemo` 迁入时,确认新版本插件与随包技能加载生效后,再移除原技能和用户规则中的重复内容。
199
227
 
200
228
  ## 默认 MCP 注册
201
229
 
@@ -255,7 +283,8 @@ Pi AI/MCP 是明确仅用于测试的开发依赖;运行时依赖和提供商
255
283
  - [厂商配置](https://github.com/tossp/pi-tsgw/tree/main/extensions/models/vendors):模型元数据、兼容性标志和思考映射。
256
284
  - [请求操作](https://github.com/tossp/pi-tsgw/blob/main/extensions/models/operations.ts):写时复制分派;DeepSeek/Claude 响应仍由 Pi 的适配器处理。
257
285
  - [内置搜索](https://github.com/tossp/pi-tsgw/blob/main/extensions/models/web-search.ts):精确的模型/协议支持范围和仅追加注入。
258
- - [宿主集成](https://github.com/tossp/pi-tsgw/blob/main/extensions/index.ts):配置、刷新、命令和生命周期快照。延迟执行的请求回调不得访问过期的会话上下文。
286
+ - [扩展总入口](https://github.com/tossp/pi-tsgw/blob/main/index.ts):包加载入口;[provider 集成](https://github.com/tossp/pi-tsgw/tree/main/extensions/provider):注册、配置、刷新、命令和生命周期快照。延迟执行的请求回调不得访问过期的会话上下文。
287
+ - [提示词注册](https://github.com/tossp/pi-tsgw/blob/main/extensions/prompts.ts):`registerPrompts` 统一入口;记忆正文位于 `prompts/memory.ts`。
259
288
 
260
289
  这些源码链接描述仓库当前的 main 分支;已安装的发行版可能有所不同。
261
290
  `AGENTS.md` 中的开发规则仅用于仓库,不属于 npm 包。
@@ -0,0 +1,13 @@
1
+ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
2
+ import { MEMORY_RULES } from "../prompts/memory.ts";
3
+
4
+ export function registerPrompts(pi: ExtensionAPI): void {
5
+ pi.on("before_agent_start", (event) => {
6
+ if (event.systemPromptOptions) {
7
+ event.systemPromptOptions.sections.tsgw_memory = MEMORY_RULES;
8
+ return;
9
+ }
10
+ // 保留已声明支持的旧宿主提示词接口。
11
+ return { systemPrompt: `${event.systemPrompt}\n\n${MEMORY_RULES}` };
12
+ });
13
+ }
@@ -0,0 +1,33 @@
1
+ import { getAgentDir } from "@earendil-works/pi-coding-agent";
2
+ import { readFileSync } from "node:fs";
3
+ import { join } from "node:path";
4
+
5
+ /**
6
+ * 扩展配置来自 Pi 设置文件(settings.json)的 `tsgw` 命名空间。
7
+ * 所有插件配置均放在此处;插件不读取环境变量
8
+ * (密钥仅由 Pi 自身的凭据解析机制处理)。
9
+ */
10
+ export interface TsgwSettings {
11
+ baseUrl?: string;
12
+ mcpUrl?: string;
13
+ tsSearch?: string;
14
+ traceHeaders?: boolean;
15
+ includeModels?: string[];
16
+ excludeModels?: string[];
17
+ }
18
+
19
+ export function readTsgwSettings(): TsgwSettings {
20
+ try {
21
+ const raw: unknown = JSON.parse(
22
+ readFileSync(join(getAgentDir(), "settings.json"), "utf8"),
23
+ );
24
+ if (raw === null || typeof raw !== "object" || Array.isArray(raw))
25
+ return {};
26
+ const tsgw = (raw as { tsgw?: unknown }).tsgw;
27
+ if (tsgw === null || typeof tsgw !== "object" || Array.isArray(tsgw))
28
+ return {};
29
+ return tsgw as TsgwSettings;
30
+ } catch {
31
+ return {};
32
+ }
33
+ }
@@ -7,7 +7,6 @@ import {
7
7
  getAgentDir,
8
8
  readStoredCredential,
9
9
  } from "@earendil-works/pi-coding-agent";
10
- import { readFileSync } from "node:fs";
11
10
  import { join } from "node:path";
12
11
  import { randomUUID } from "node:crypto";
13
12
  import {
@@ -17,19 +16,18 @@ import {
17
16
  modelsForRoot,
18
17
  normalizeRoot,
19
18
  type ModelFilter,
20
- } from "./models/catalog.ts";
21
- import { getGatewayModelIds } from "./models/gateway-catalog.ts";
22
- import { applyModelOperations } from "./models/operations.ts";
23
- import { registerSearch } from "./search.ts";
19
+ } from "../models/catalog.ts";
20
+ import { getGatewayModelIds } from "../models/gateway-catalog.ts";
21
+ import { applyModelOperations } from "../models/operations.ts";
22
+ import { registerSearch } from "../search/index.ts";
24
23
  import {
25
24
  catalogLabel,
26
25
  catalogDiagnostics,
27
26
  searchLabel,
28
27
  type CatalogStatus,
29
28
  } from "./status.ts";
30
- import type { ThinkingLevel, WebSearchMode } from "./models/_tools.ts";
31
- import { registerUploadTool } from "./upload/index.ts";
32
- import { registerTsgwMcp } from "./mcp.ts";
29
+ import type { ThinkingLevel, WebSearchMode } from "../models/_tools.ts";
30
+ import type { TsgwSettings } from "./config.ts";
33
31
 
34
32
  /**
35
33
  * 在生命周期上下文仍有效时,复制供应商钩子所需的数据。
@@ -50,36 +48,6 @@ interface RequestModel {
50
48
  baseUrl: string;
51
49
  }
52
50
 
53
- /**
54
- * 扩展配置来自 Pi 设置文件(settings.json)的 `tsgw` 命名空间。
55
- * 所有插件配置均放在此处;插件不读取环境变量
56
- * (密钥仅由 Pi 自身的凭据解析机制处理)。
57
- */
58
- interface TsgwSettings {
59
- baseUrl?: string;
60
- mcpUrl?: string;
61
- tsSearch?: string;
62
- traceHeaders?: boolean;
63
- includeModels?: string[];
64
- excludeModels?: string[];
65
- }
66
-
67
- function readTsgwSettings(): TsgwSettings {
68
- try {
69
- const raw: unknown = JSON.parse(
70
- readFileSync(join(getAgentDir(), "settings.json"), "utf8"),
71
- );
72
- if (raw === null || typeof raw !== "object" || Array.isArray(raw))
73
- return {};
74
- const tsgw = (raw as { tsgw?: unknown }).tsgw;
75
- if (tsgw === null || typeof tsgw !== "object" || Array.isArray(tsgw))
76
- return {};
77
- return tsgw as TsgwSettings;
78
- } catch {
79
- return {};
80
- }
81
- }
82
-
83
51
  function rootForRuntime(configured: string | undefined): string {
84
52
  try {
85
53
  return normalizeRoot(configured);
@@ -197,10 +165,9 @@ async function resolveEffectiveModels(
197
165
  return { models, gatewayIds, catalog: { ...catalog, count: models.length } };
198
166
  }
199
167
 
200
- export default async function registerTsgw(pi: ExtensionAPI): Promise<void> {
201
- registerUploadTool(pi);
202
- const settings = readTsgwSettings();
203
- registerTsgwMcp(pi, settings.mcpUrl);
168
+ export async function registerTsgwProvider(
169
+ pi: ExtensionAPI, settings: TsgwSettings,
170
+ ): Promise<void> {
204
171
  const root = rootForRuntime(settings.baseUrl);
205
172
  const defaultSearchMode: WebSearchMode =
206
173
  settings.tsSearch === "cached" || settings.tsSearch === "live"
@@ -1,5 +1,5 @@
1
- import type { WebSearchMode } from "./models/_tools.ts";
2
- import { DEFAULT_GATEWAY_MODEL_CACHE_TTL_MS } from "./models/gateway-catalog.ts";
1
+ import type { WebSearchMode } from "../models/_tools.ts";
2
+ import { DEFAULT_GATEWAY_MODEL_CACHE_TTL_MS } from "../models/gateway-catalog.ts";
3
3
 
4
4
  export interface CatalogStatus {
5
5
  count: number;
@@ -1,8 +1,8 @@
1
1
  import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
2
- import { builtinSearchSupport, resolveSearchDelegate } from "./models/web-search.ts";
3
- import type { WebSearchMode } from "./models/_tools.ts";
4
- import { searchLabel, type SearchSupport } from "./status.ts";
5
- import { registerSearchProxyTool, SEARCH_PROXY_TOOL } from "./search-proxy.ts";
2
+ import { builtinSearchSupport, resolveSearchDelegate } from "../models/web-search.ts";
3
+ import type { WebSearchMode } from "../models/_tools.ts";
4
+ import { searchLabel, type SearchSupport } from "../provider/status.ts";
5
+ import { registerSearchProxyTool, SEARCH_PROXY_TOOL } from "./proxy.ts";
6
6
 
7
7
  interface SearchOptions {
8
8
  defaultMode: WebSearchMode;
@@ -1,9 +1,9 @@
1
1
  /** 搜索代理复用 Pi 的注册表、身份认证与协议适配器。 */
2
2
  import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
3
3
  import { Type } from "typebox";
4
- import { isPlainObject, type WebSearchMode } from "./models/_tools.ts";
5
- import { applyModelOperations } from "./models/operations.ts";
6
- import { builtinSearchSupport, type SearchDelegate } from "./models/web-search.ts";
4
+ import { isPlainObject, type WebSearchMode } from "../models/_tools.ts";
5
+ import { applyModelOperations } from "../models/operations.ts";
6
+ import { builtinSearchSupport, type SearchDelegate } from "../models/web-search.ts";
7
7
 
8
8
  export const SEARCH_PROXY_TOOL = "tsgw_search";
9
9
  interface SearchProxyOptions {
package/index.ts ADDED
@@ -0,0 +1,15 @@
1
+ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
2
+ import { registerTsgwMcp } from "./extensions/mcp.ts";
3
+ import { registerPrompts } from "./extensions/prompts.ts";
4
+ import { readTsgwSettings } from "./extensions/provider/config.ts";
5
+ import { registerTsgwProvider } from "./extensions/provider/index.ts";
6
+ import { registerUploadTool } from "./extensions/upload/index.ts";
7
+
8
+ /** 插件总入口:保持能力注册顺序,实现由各模块维护。 */
9
+ export default async function registerTsgw(pi: ExtensionAPI): Promise<void> {
10
+ registerUploadTool(pi);
11
+ registerPrompts(pi);
12
+ const settings = readTsgwSettings();
13
+ registerTsgwMcp(pi, settings.mcpUrl);
14
+ await registerTsgwProvider(pi, settings);
15
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pi-tsgw",
3
- "version": "0.0.17",
3
+ "version": "0.1.0",
4
4
  "description": "面向 TOSSP AIH gateway 的 Pi 扩展:按厂商维护模型目录与思考策略,支持 openai-completions、openai-responses、anthropic-messages 和 google-generative-ai 协议。",
5
5
  "type": "module",
6
6
  "keywords": [
@@ -17,14 +17,14 @@
17
17
  },
18
18
  "pi": {
19
19
  "extensions": [
20
- "./extensions/index.ts"
20
+ "./index.ts"
21
21
  ],
22
22
  "skills": [
23
23
  "./skills"
24
24
  ]
25
25
  },
26
26
  "scripts": {
27
- "test": "tsc -p tsconfig.test.json && node dist/extensions/index.test.js && node dist/extensions/status.test.js && node dist/extensions/search.test.js && node dist/extensions/search-proxy.test.js && node dist/extensions/search-host-integration.test.js && node dist/extensions/status-integration.test.js && node dist/extensions/models/gateway-catalog-metadata.test.js && node dist/extensions/models/operations.test.js && node dist/extensions/models/catalog.test.js && node dist/extensions/models/web-search.test.js && node dist/extensions/models/gateway-catalog.test.js && node dist/extensions/models/gateway-catalog-isolation.test.js && node dist/extensions/models/vendor-strategies.test.js && node dist/extensions/host-integration.test.js && node dist/extensions/mcp.test.js && node dist/extensions/mcp-host-integration.test.js && node dist/extensions/skills.test.js && node dist/extensions/skill-resources.test.js && node dist/extensions/upload/protocol.test.js && node dist/extensions/upload/schema.test.js && node dist/extensions/upload/uploader.test.js && node dist/extensions/upload/transport.test.js && node dist/extensions/upload/host-integration.test.js && node dist/extensions/upload/readiness-host.test.js",
27
+ "test": "tsc -p tsconfig.test.json && node dist/extensions/provider/index.test.js && node dist/extensions/prompts.test.js && node dist/extensions/provider/status.test.js && node dist/extensions/search/index.test.js && node dist/extensions/search/proxy.test.js && node dist/extensions/search/host-integration.test.js && node dist/extensions/provider/status-integration.test.js && node dist/extensions/models/gateway-catalog-metadata.test.js && node dist/extensions/models/operations.test.js && node dist/extensions/models/catalog.test.js && node dist/extensions/models/web-search.test.js && node dist/extensions/models/gateway-catalog.test.js && node dist/extensions/models/gateway-catalog-isolation.test.js && node dist/extensions/models/vendor-strategies.test.js && node dist/index.test.js && node dist/extensions/mcp.test.js && node dist/extensions/mcp-host-integration.test.js && node dist/extensions/skills.test.js && node dist/extensions/skill-resources.test.js && node dist/extensions/upload/protocol.test.js && node dist/extensions/upload/schema.test.js && node dist/extensions/upload/uploader.test.js && node dist/extensions/upload/transport.test.js && node dist/extensions/upload/host-integration.test.js && node dist/extensions/upload/readiness-host.test.js",
28
28
  "test:upload:live": "tsc -p tsconfig.test.json && node dist/extensions/upload/live.test.js"
29
29
  },
30
30
  "peerDependencies": {
@@ -0,0 +1,19 @@
1
+ /** 从用户规则迁入的记忆体系与既有维护授权。 */
2
+ export const MEMORY_RULES = `## 记忆体系
3
+
4
+ \`ctx_memory\` 称为“系统记忆”,smemo/Blinko 称为“记忆系统”,两者不混称。
5
+
6
+ | 入口 | 分工 |
7
+ | --- | --- |
8
+ | 项目多层级 \`AGENTS.md\` | 项目指引、长期专有规则、方法和资料入口 |
9
+ | \`ctx_memory\` | 记录和更新跨会话需要延续的项目知识 |
10
+ | \`ctx_search\`、\`ctx_expand\`、\`ctx_reduce\` | 检索历史、恢复原始内容、释放已用完的上下文 |
11
+ | \`ctx_note\`、\`todowrite\` | 分别管理后续事项和当前任务 |
12
+ | \`skill:tsgw-smemo\` → Blinko | 维护跨设备共享知识,职责与操作按技能执行 |
13
+
14
+ - ctx 在同设备的 PiWeb/OC 间互通,项目与会话仍有作用范围,不跨设备共享;Blinko 由各设备 PiWeb/OC 共用。个人倾向由 Magic Context 的用户记忆机制(\`user-profile\`)维护,不另存为项目记忆或写入 smemo。
15
+ - 先利用已注入规则和当前上下文,再按需通过 ctx 检索、展开历史;需要共享知识或外部调研时使用 smemo,不要求每次遍历所有入口。
16
+ - 新结论按职责及时更新对应载体:工作延续用 ctx,长期项目规则归 \`AGENTS.md\`,共享知识按 smemo 技能沉淀;用摘要和引用关联,不重复维护完整正文。
17
+ - 工具细则以实时提示和技能为准;规则与技能在获准范围内跨端统一维护,单端修改不代表已经同步。
18
+
19
+ - smemo 条目内容维护(含永久删除)的持续授权见 \`skill:tsgw-smemo\`,不由此放宽文件、Git、服务、凭据或权限操作边界。`;
@@ -0,0 +1,179 @@
1
+ ---
2
+ name: tsgw-smemo
3
+ description: 当用户提到 smemo、Blinko、记忆或笔记时用于判断记录落点;发现外部调研、通用知识、有效资讯及可复用解决方案时主动检索和维护。Blinko 是各设备 PiWeb/OC 共用的统一知识库,不记录个人倾向或具体现场事实;项目资料与本机 ctx 另有职责。
4
+ license: MIT
5
+ compatibility: Pi / Pi Web and OpenCode with Blinko tools from the ts_tool MCP server
6
+ metadata:
7
+ category: workflow
8
+ workflow: memory-management
9
+ ---
10
+ # 记忆系统 (smemo)
11
+
12
+ 本技能在各设备的 PiWeb/OC 中使用同一正文和参考资料,统一职责与维护权限;宿主差异仅限工具接入。跨设备共享的是 Blinko 知识,技能和规则文件仍需在各设备的本地维护来源同步更新。
13
+
14
+ ## 定位与职责边界
15
+
16
+ - **记忆系统**:通过 Blinko 跨设备、跨会话、跨项目共享外部知识、通用资料、经核验有效的资讯及可复用解决方案。
17
+ - **smemo**:这套职责与维护流程的技能名;不是另一份数据库。
18
+ - **系统记忆**:Magic Context 的 `ctx_memory` 及相关工作延续机制,PiWeb/OC 在同一设备的共享数据库下互通;项目、会话仍有作用范围,各设备数据库不共享,不能用它冒充 Blinko 已写入。
19
+ - 插件注入的记忆规则治理整套体系;项目多层级 `AGENTS.md` 维护项目指引、长期专有规则与方法,详细设计及现场资料按项目既有分类归位。
20
+
21
+ ### 不进入 Blinko 的内容
22
+
23
+ - **个人倾向性信息**:个人偏好、沟通风格、行为画像及其推断。由 Magic Context 原生全局用户记忆/`<user-profile>` 机制依实际配置处理;用户明确要求持续执行的规范写入用户级规则,不通过 smemo 维护画像。
24
+ - **具体现场事实**:设备身份、地址、运行状态、实际部署、配置、版本、权限、入口映射及一次性排障观察,即使稳定、需要跨设备查询或属于调研证据,也不写入 Blinko。正式事实归所属项目资料,需要工作接续时可留本机 ctx 摘要,不能只搬到某台 ctx 就称已共享。
25
+ - 无法脱离项目成立的内部需求、设计、决策与实现约定,及必须即时执行的编排、授权、提示词行为规则。规则落适用 `AGENTS.md`/代理提示词,详细内容落项目权威资料。
26
+ - 当前执行步骤、临时状态、未定项目方案和明显无后续价值的输出。当前步骤用 `todowrite`,延期意图及发现用 `ctx_note`,讨论与原始证据留历史。
27
+ - 密钥、凭据、受保护内容及不应进入共享知识库的敏感材料。
28
+
29
+ 上述排除项不因一句“记住”而改变落点。已有现场记录按单独安排的迁移范围处理,不因技能更新顺手盘点、迁移或清空旧库。
30
+
31
+ ## 主动触发与沉淀标准 (MUST)
32
+
33
+ 在当前任务或相关知识维护中发现以下内容,应主动检索、写入或更新,不必等待用户逐条提醒:
34
+
35
+ - 外部调研形成的通用/外部知识(必须沉淀,不以项目已采用为条件);
36
+ - 可跨设备复用的通用知识、流程、解决方案、最佳实践及适用边界;
37
+ - 外部/通用知识范围内的稳定事实和经核验仍有效的资讯;
38
+ - 从反复问题、失败经验或纠正中提炼出的可复用知识,不复制具体现场过程;
39
+ - 用户明确要求保留、且符合职责边界的其他非敏感长期信息;该类信息不是默认主动采集类别。
40
+
41
+ 这是开放清单,不要求苛刻证明未来一定复用。时效短不等于没有价值:有效资讯或历史外部结论可保留核验时间和适用边界,但不能用这一点绕过个人倾向、现场事实或敏感信息的排除规则。
42
+
43
+ ## 检索与记录质量
44
+
45
+ ### 冲突处理
46
+
47
+ - 普通记忆的旧笔记与新事实冲突时 → 更新原笔记并记录变更原因
48
+ - 外部知识的范围、冲突和历史结论按“外部知识沉淀”处理;不要把相近主题误作重复笔记
49
+ - 优先保持信息的完整性而不是堆砌数量
50
+
51
+ ### 重复记忆处理 (MUST)
52
+
53
+ - 使用记忆系统时发现同一范围的重复或相似笔记 → 搜索并确认现有主记录,优先更新它
54
+ - 对其他重复笔记,先提取仍有价值的差异内容,合并写入主记录
55
+ - 可自主修正标签、更新或合并记录、归档或删除无价值重复记录及恢复误归档记录;方向或范围不同的外部知识应独立且互相关联,不得错误合并。
56
+
57
+ ### 标签 = 关键词提取
58
+
59
+ 核心原则:**多标签 = 多维度关联**
60
+
61
+ - 从笔记内容中提取多个关键词作为标签
62
+ - 用词保持一致:避免 "#Linux" 和 "#linux" 混用
63
+ - 实践中自然生长:不需要预设复杂标签体系
64
+
65
+ ### 层级结构
66
+
67
+ ```
68
+ 技术类: #windows #linux #debian #python
69
+ 运维类: #运维/晨云 #运维/川大 #运维信息
70
+ 技巧类: #技巧/windows #技巧/linux #技巧/ntp
71
+ 业务类: #晨云 #川大 #水利
72
+ ```
73
+
74
+ ### 查询策略 (MUST)
75
+
76
+ - **先分流,再按需请求 Blinko**:提到“记忆”时先判断职责;项目现场、个人倾向或当前任务不因此触发外部搜索。需要查询或维护共享知识时检索 Blinko,本轮已查且仍可用的结果可复用。非明确外部调研,且当前上下文或 ctx 已足够、本次无需查询或维护 Blinko 时,可不请求 Blinko;明确外部调研仍须历史查询、当前核验与自动沉淀。
77
+ - **先用关键词,再用标签组合**:关键词宽搜 -> 标签精确
78
+ - 需要外部知识时,先查项目资料和相关记忆,将命中内容作为历史基线:复用来源和关键词,识别分歧、边界与证据缺口,提高本轮调研的准确性和广度。
79
+ - 对明确的外部调研任务,命中记录不得自动停止外部调研;按本次问题开展当前外部补充或事实核验。已有记忆可决定检索范围和强度,但不能替代事实核验;核验强度应与知识的风险和时效相关,无须每次无差别从零开始。
80
+ - 命中条目时检查其来源、适用边界、状态和时效信息,并为后续比较保留稳定条目 ID 或链接。
81
+
82
+ ### 标签校验
83
+
84
+ **命中且复用时校验**:
85
+
86
+ - 搜索命中的笔记,检查内容关键词是否反映在标签中
87
+ - 如果笔记提到 "dify" 但没有 "#dify" 标签 → 添加
88
+ - 如果笔记是关于 Linux 但用了根级 "linux" 而不是 "#技巧/linux" → 修正
89
+
90
+ ### 维护、清理与验证 (MUST)
91
+
92
+ - **持续维护授权包含删除**:与当前任务或知识维护直接相关的创建、单条或批量更新、标签调整、合并、归档、恢复及删除(含永久删除),模型可自主判断执行,无须逐条确认;不强制先标记 `#待删除`、归档或备份。
93
+ - 写入前检查同范围主记录,优先更新;重复记录先合并独有价值并验证主记录,再按价值决定保留、归档或删除。方向或范围不同的知识不要错误合并。
94
+ - 外部知识失效、被替代或存在冲突时,根据证据和历史价值更新、关联、归档或删除;需要追溯的结论可用 `#已过期`、`#已替代`、`#待复核`、`#待确认` 等状态,不能只因陈旧就判断无价值。
95
+ - 不确定内容保留未决依据,先核验,不伪造一致结论。已有现场条目的迁移按所属项目和当次确认范围执行,保留有价值通用部分与必要引用,不借维护授权展开无关全库清理。
96
+ - 先读取实际目标及工具定义,再做相关增量;验证返回结果和更新后正文/状态。删除须按实际入口区分回收站与永久删除,不能把普通列表无命中当作已永久删除的证据,也不承诺永久删除可恢复。
97
+ - 每次创建、更新、合并、归档、恢复或删除后,回报实际动作、条目 ID、简短变化/理由及替代条目 ID(如有)。不输出敏感内容,不把未执行动作当作完成。
98
+ - 普通更新利用已具备的版本历史追溯;不为自由删除承诺不存在的恢复能力。维护授权不扩展到文件、Git、服务、凭据、访问权限或定时任务。
99
+
100
+ ## 外部知识沉淀 (MUST)
101
+
102
+ 1. **建立历史基线**:先搜索相关记忆,复用既有来源和关键词,识别与本次问题的分歧、范围和证据缺口;命中不是跳过调研的条件。
103
+ 2. **进行本轮核验**:对明确的外部调研任务,始终按本次问题做当前外部补充或验证。比较本次问题范围、技术/产品/规范版本、来源发布日期或内容版本、证据检索/事实核验时间,以及适用环境和最佳实践变化。
104
+ 3. **按比较结果维护**:
105
+ - 同一范围且仍有效:补充最新证据,记录本次核验信息。
106
+ - 同一范围但事实或最佳实践变化:更新当前结论,明确旧结论的历史适用范围、被替代时间和原因,并标记 `#已替代`(或适用的状态)。
107
+ - 相近主题但方向或范围不同:建立独立且互相关联的条目;不得粗暴覆盖或错误去重。每个主题保留明确的当前结论入口。
108
+ - 新旧证据冲突且无法裁决:保留冲突和各自证据,标记 `#待确认`(或等价状态),不得伪造统一结论。
109
+ 4. **调研后 upsert**:检查同范围主记录,已在本轮确认且仍适用的检索结果可复用;仅同一范围时优先更新主条目,不存在时新建。外部调研形成的外部知识必须写入,不因尚未被项目采用或未证明可复用而跳过。
110
+ 5. **项目侧引用**:项目 docs 只记录项目的采用或否决判断、取舍理由和应用方式,并引用对应记忆条目及必要的采用时版本或核验时间,不复制完整调研正文。
111
+
112
+ ### 外部知识条目正文格式
113
+
114
+ 每个条目保持简洁、可检索和可维护,至少包含标题、标签及以下字段:
115
+
116
+ ```markdown
117
+ #领域 #主题 [#状态]
118
+
119
+ ## 标题
120
+
121
+ - 调研问题/范围:...
122
+ - 来源链接或对象标识:...
123
+ - 来源版本/发布日期或内容版本:...(与时效相关时)
124
+ - 关键证据或定位:...(链接、章节、段落、版本或可复核摘录)
125
+ - 证据检索/事实核验时间:...(与时效相关时)
126
+ - 结论:...
127
+ - 适用版本/环境、边界或限制:...
128
+ - 历史关系/替代说明:...(相关条目、旧适用范围、被替代时间与原因;适用时)
129
+ ```
130
+
131
+ - 视需要加入状态;与时效有关时必须记录来源版本/发布日期、证据检索或事实核验时间、适用版本或环境。
132
+ - Blinko 自动维护的创建/更新时间仅是条目操作元数据,不等于来源时间、最后事实核验时间或结论有效期;不要在正文机械重复,也不得将“最后修改时间”当作知识仍有效的证据。
133
+ - 当前权威结论必须有明确入口;历史结论不得伪装为当前最佳实践,但应保留可追溯的旧适用范围和替代原因。
134
+
135
+ - 适用环境记录可复现的软件/规范条件,不记录具体受管设备的身份、当前版本、IP、端口、部署路径或权限。现场证据和项目采用记录归所属项目资料,不随调研正文进入 Blinko。
136
+
137
+ ## MCP 接入与工具选择
138
+
139
+ 只规定工具职责,不固定跨宿主调用前缀或参数模板。以下 `blinko__*` 是服务端工具名,实际名称、参数类型和能力以当前会话定义为准。
140
+
141
+ ### 宿主适配
142
+
143
+ - **Pi/Pi Web**:使用 Pi 原生 MCP。工具未直接暴露且本会话提供 `codemode` 时,用 `searchTools()`/`describeTool()` 发现并读取定义,再按实时 schema 调用。原生注册名通常为 `mcp__ts_tool__blinko__*`,仍以发现结果为准;`/mcp` 用于连接管理,不是工具调用网关。
144
+ - **OpenCode**:使用当前 OC 会话提供的工具清单或已提供的发现入口,不套用 Pi 专属 codemode/MCP 前缀,也不沿用旧适配器格式。
145
+ - 工具未提供、连接或认证失败时说明限制;不猜测调用名、不寻找或回显凭据、不放宽访问控制,不用其他记忆入口冒充 Blinko 写入成功。
146
+
147
+ | 服务端工具 | 用途 |
148
+ | --- | --- |
149
+ | `blinko__searchBlinko` | 关键词宽搜,再按标签与实际过滤能力检索 |
150
+ | `blinko__upsertBlinko` | 无同范围主记录时创建 |
151
+ | `blinko__updateBlinko` | 修正、补充、维护状态或合并到主记录 |
152
+ | `blinko__deleteBlinko` | 按持续维护授权删除无保留价值的条目 |
153
+ | `blinko__createComment` | 当前任务确有需要时评论 |
154
+ | `blinko__createScheduledTask`/`blinko__listScheduledTasks`/`blinko__deleteScheduledTask` | 定时任务的对应操作;不从条目维护授权推定可创建、修改或删除定时任务 |
155
+
156
+ 定时任务只有用户明确表达相应意图时才处理。不要从技能或历史 API 摘录复制参数;数组、对象、布尔值和数字须按实时 schema 使用原生类型。
157
+
158
+ ## 分流与维护示例
159
+
160
+ ```text
161
+ 核验官方文档:软件 X v1.2 支持条件 Y
162
+ → 维护 Blinko 主条目,记录来源、版本、核验时间和适用边界。
163
+
164
+ 发现某台设备实际运行版本或服务配置
165
+ → 回写该项目正式资料,按需更新本机 ctx,不写入 Blinko。
166
+
167
+ 归纳用户个人沟通风格/行为倾向
168
+ → 属原生 user-profile 机制;明确执行规范归用户级规则,不写入 Blinko。
169
+
170
+ 确认重复条目含少量独有信息
171
+ → 合入主记录并回读验证,再自主归档或删除重复条目,回报 ID 与理由。
172
+
173
+ 用户要求每天提醒
174
+ → 属定时任务意图,核对具体范围后处理,不借普通条目维护权限自行建任务。
175
+ ```
176
+
177
+ ## 参考资料
178
+
179
+ - [Blinko 操作指南](./references/blinko-guide.md):宿主适配、查询/归档/删除边界及历史 API 线索。
@@ -0,0 +1,111 @@
1
+ # Blinko 操作指南
2
+
3
+ 本参考与 `../SKILL.md` 在各设备 PiWeb/OC 使用同一内容,职责与授权以主技能和插件注入的记忆规则为准。
4
+
5
+ ## 日常维护边界
6
+
7
+ - 仅维护符合 smemo 职责的跨设备共享知识;不新增个人倾向、现场事实、项目专有状态或敏感信息。
8
+ - 与当前任务或相关知识维护直接相关的创建、更新、合并、标签调整、归档、恢复及删除(含永久删除)均可自主执行并事后回报,不要求逐条授权,也不强制先标记待删除或备份。
9
+ - 合并保留独有价值后再处理重复条目;有历史/引用价值的外部结论保留必要追溯。永久删除不承诺可恢复。
10
+ - 已有现场记录另按确认范围迁移到所属项目资料,不能借技能同步顺手清理旧库。定时任务、其他文件/服务和凭据权限不包含在条目维护授权内。
11
+
12
+ ## MCP 接入
13
+
14
+ | 宿主 | 操作方式 |
15
+ | --- | --- |
16
+ | Pi/Pi Web | Pi 原生 MCP;本会话有 codemode 时通过 `searchTools()`/`describeTool()` 获取工具定义;原生工具名以实际发现结果为准 |
17
+ | OpenCode | 使用当前会话已提供的 MCP 工具及发现入口,不复制 Pi 专属调用前缀或调用方式 |
18
+
19
+ `blinko__searchBlinko`、`blinko__upsertBlinko`、`blinko__updateBlinko`、`blinko__deleteBlinko` 分别承担检索、创建、更新和删除。实际名称、参数及操作效果以实时定义为准,不用本页历史 API 片段代替工具 schema。
20
+
21
+ ### 查询与状态验证
22
+
23
+ 1. 先关键词宽搜,再按标签精确筛选;同范围先更新主记录。
24
+ 2. 普通列表无命中时检查当前工具的归档/回收站过滤能力,如支持,可定向查询相应状态;不能据此断言条目不存在或已永久删除。
25
+ 3. 合并/更新后回读确认正文和状态;删除前确认实际入口是移入回收站还是永久删除,删除后按工具支持的状态查询或明确结果验证。
26
+ 4. 工具或认证不可用时报告原因,只用已提供的入口;不猜工具名,不通过搜索凭据或临时放宽权限绕过故障。
27
+
28
+ ## 历史 API 调查线索
29
+
30
+ 以下是此前保留的源码定位及接口摘录,**没有绑定当前运行版本**。路径、行号、字段和删除语义可能变化,仅供必要时调查;实际 API 操作前须核验目标版本、受管入口、身份和 schema。普通维护优先使用已授权 MCP,不因 MCP 故障推定已获直接 API 认证授权。
31
+
32
+ ## API 源码位置
33
+
34
+ - **文件**: `server/routerTrpc/note.ts`
35
+ - **路由**: `noteRouter.updateMany`
36
+ - **行号**: 1278-1297
37
+
38
+ ### 相关批量操作 (同一文件)
39
+
40
+ | 端点 | 路由路径 | 行号 |
41
+ | ---------- | --------------------- | --------- |
42
+ | `updateMany` | `/v1/note/batch-update` | 1278-1297 |
43
+ | `trashMany` | `/v1/note/batch-trash` | 1298-1306 |
44
+ | `deleteMany` | `/v1/note/batch-delete` | 1307-1333 |
45
+
46
+ ### batch-update 源码
47
+
48
+ ```typescript
49
+ updateMany: authProcedure
50
+ .meta({ openapi: { method: 'POST', path: '/v1/note/batch-update', summary: 'Batch update note', protect: true, tags: ['Note'] } })
51
+ .input(
52
+ z.object({
53
+ type: z.union([z.nativeEnum(NoteType), z.literal(-1)]).default(-1),
54
+ isArchived: z.union([z.boolean(), z.null()]).default(null),
55
+ isRecycle: z.union([z.boolean(), z.null()]).default(null),
56
+ ids: z.array(z.number()),
57
+ }),
58
+ )
59
+ .output(z.any())
60
+ .mutation(async function ({ input, ctx }) {
61
+ const { type, isArchived, isRecycle, ids } = input;
62
+ const update: Prisma.notesUpdateInput = {
63
+ ...(type !== -1 && { type }),
64
+ ...(isArchived !== null && { isArchived }),
65
+ ...(isRecycle !== null && { isRecycle }),
66
+ };
67
+ return await prisma.notes.updateMany({ where: { id: { in: ids }, accountId: Number(ctx.id) }, data: update });
68
+ }),
69
+ ```
70
+
71
+ ## 常用 API 端点
72
+
73
+ ### 笔记列表
74
+
75
+ **文件**: `server/routerTrpc/note.ts`
76
+ **行号**: 26-65
77
+
78
+ ```typescript
79
+ list: authProcedure
80
+ .meta({ openapi: { method: 'POST', path: '/v1/note/list', summary: 'Query notes list', protect: true, tags: ['Note'] } })
81
+ .input(
82
+ z.object({
83
+ tagId: z.union([z.number(), z.null()]).default(null),
84
+ page: z.number().default(1),
85
+ size: z.number().default(30),
86
+ orderBy: z.enum(['asc', 'desc']).default('desc'),
87
+ type: z.union([z.nativeEnum(NoteType), z.literal(-1)]).default(-1),
88
+ isArchived: z.union([z.boolean(), z.null()]).default(false).optional(),
89
+ isShare: z.union([z.boolean(), z.null()]).default(null).optional(),
90
+ isRecycle: z.boolean().default(false).optional(),
91
+ searchText: z.string().default('').optional(),
92
+ withoutTag: z.boolean().default(false).optional(),
93
+ withFile: z.boolean().default(false).optional(),
94
+ withLink: z.boolean().default(false).optional(),
95
+ isUseAiQuery: z.boolean().default(false).optional(),
96
+ startDate: z.union([z.date(), z.null(), z.string()]).default(null).optional(),
97
+ endDate: z.union([z.date(), z.null(), z.string()]).default(null).optional(),
98
+ hasTodo: z.boolean().default(false).optional(),
99
+ }),
100
+ )
101
+ ```
102
+
103
+ ## 定时任务线索
104
+
105
+ 此前记录的 `ArchiveJob`、`DBJob`、`RebuildEmbeddingJob`、`RecommandJob`、`AIScheduledTaskJob` 是调查线索,不证明当前实例正在执行这些任务。当前任务是否启用、何时运行和能否修改须按实际版本核验;不由普通条目维护授权推定可以新建、修改或删除调度。
106
+
107
+ ## 相关定位
108
+
109
+ - 技能职责与维护流程:[smemo 主技能](../SKILL.md)。
110
+ - 官方源码项目:`blinkospace/blinko`,笔记路由线索 `server/routerTrpc/note.ts`。
111
+ - 受管实例的 API 文档/OpenAPI 入口与身份从既有配置确认,不将具体设备现场或认证复制进共享笔记。