ima知识库 · IMA 知识库操作规范（v2 · 付费版）

> 本 Skill 把三份规则文档固化为可执行流程：
> references/00_库说明.md + references/标准卡片模板.md + references/文件提取规则.md。
> 完整原文见 references/，本文件只做路由与硬约束。
> v2 关键特性：point.md 逻辑速查层（绝对最高检索优先级）、七分类序列号体系、
> 四级引用优先级、回答四段结构、素材与沉淀统一 YAML 头、seq 字段、提取产物强制 YAML 头。

使用前配置（买家必读）

本 Skill 作用于你自己的 IMA 知识库，使用前需要三处配置（均为一次性）：

• 目录结构（00-Inbox / 01-Projects / 02-Areas / 03-Resources / 04-Skill / 05-Archives / Idea_灵感）
  需在买家自己的知识库中先建好；子目录规则见 references/00_库说明.md 第二节。
• 各大文件夹的 folder_id 由买家建目录后自行记录，本包不含任何作者私有知识库 ID。

存储通道（免密钥 · 默认路径）

本 Skill 不依赖 Client ID / API Key。日常"存内容"一律走 IMA 连接器（已授权会话），不走 OpenAPI。

硬约束
1. 必须显式传 knowledge_base_id 与 folder_id —— 不传会落到默认库，落点不可控；目录落点按流程 1 的路由结果填写。
2. create_media 的 file_size 必须与实际字节数一致；PUT 时原样携带 auth_headers（含 Content-Type / Content-Length / x-cos-acl），否则签名校验失败。
3. 上传成功后才调 add_knowledge；Markdown 的 media_type=7。
4. 禁止把 Client ID / API Key、ima_api.cjs、COS STS 凭证脚本当作默认存储路径。

能力边界（诚实说明）
- 连接器没有建文件夹接口。仅当初始化目录（00-Inbox…Idea_灵感 及子目录）尚未建立时，才需要一次性走 OpenAPI create_folder（需凭证）；目录建好后，后续所有存内容操作都不再需要密钥。
- IMA 无删除 / 移动 / 覆盖接口 → 更新文档 = 重传 + 在客户端手动删旧版；duplicate_name_strategy=REPLACE 实测无效，勿依赖。

为什么取消密钥流程（根因）
此前把「鉴权失败」误判为"两套环境的密钥不通用"，实际是 upload_mode 用错：连接器返回的是预签名直传（mode=1），却拿 COS STS 脚本去上传，才报 403 InvalidAccessKeyId。改用 presigned_url 后全程无需凭据，密钥流程属于多余环节，故从规范中移除。

六类任务路由

> 联动闭环：流程 3 产出提取产物（素材）→ 流程 4 提炼逻辑入 point.md → 流程 2 重做成沉淀卡片 → 流程 5 回答时优先引用 point.md。

point.md 七分类速查表（必记）

序列号格式：分类前缀 + 三位号（M001、C002）；seq 字段写入卡片 YAML。

流程 1｜归档（决定内容放哪）

• 02-Areas 认知领域：光伏产业认知库 / 储能逻辑认知 / 基金投资方法论 / 宏观周期认知 / 营销 / 处世哲学 / 谈心（可按买家领域自行调整）
• 归档动作（v2）：新内容先入 00-Inbox → 判断类型 → 提炼并追加到 point.md（分配序列号） → 归档至 P/A/R/Skill/Idea → 过期后移 05-Archives

流程 2｜卡片（统一 YAML 头，素材与沉淀一律携带）

最低必填 5 项：uid type tags folder related
可选：source created updated status confidence valid_start valid_end seq
禁止自定义新增字段（seq 是唯一受控增补字段）。

• 四段式固定：核心 → 我的思考 → 我怎么用 → 关联
• 原子化：一卡一事，正文 ≤ 1000 字
• uid：KB-年份-三位序号（全局唯一）；seq：point.md 序列号，未沉淀则留空
• 沉淀卡片必须同时产出【核心结论】与【核心逻辑链】，并同步追加到 point.md 对应分类分区
• 完整模板与素材 YAML 头示例见 references/标准卡片模板.md

流程 3｜提取（三段结构，YAML 头强制置顶）

产物 = YAML 头 + 叙事解读区 + 图谱元数据区

0. 先写 YAML 头（type: 素材卡片，folder: 03-Resources/...），置于文档最前
1. 判类型 → Schema A（专利/科技文献）或 Schema B（教学研究）
2. 叙事区五段递进：背景痛点 → 整体框架 → 核心内容 → 核心结论 → 价值/局限/展望
3. 元数据区置文末，用 ---图谱元数据开始--- / ---图谱元数据结束--- 包裹
4. 元数据：一句一关系、不引申、不写评价、实体命名一致、字段不得新增或改名（缺项标「未提及」）
5. 对照质量校验清单自检（首项即「YAML 头齐全且位于最前」）

Schema A / B 字段全集见 references/文件提取规则.md 第三节。

流程 4｜沉淀至 point.md（七分类提炼，v2 新增）

通用铁律（4 条，不可违反）：
1. 只提炼逻辑，不复述数据（数字留原文）
2. 判断要明确，不模棱两可
3. 必须写核心假设 / 边界条件
4. 冲突时标注 ⚠️ 并两边并列，不强行调和

追加 SOP：
1. 判断文档属于七分类中哪一类（跨类则拆多块）
2. 按该分类输出格式写逻辑块，分配序列号（该分类已有最大号 +1）
3. 在 point.md「文件序列号总索引」追加一行：序列号 / 分类 / 标题 / 入库时间 / 标签
4. 在对应分类分区追加逻辑块
5. 与已有逻辑冲突 → 标注 ⚠️ 并并列两边依据、分歧原因、适用条件

每条逻辑块必备要素：
- 序列号 + 分类 + 文档标题 + 入库时间 + 标签
- 【核心逻辑链】：按对应分类输出格式撰写
- 【核心结论】：编号结论（如 结论 M1.1）
- 冲突标注：⚠️ 冲突提示 / ⚠️ 认知差异 / ⚠️ 观点差异 / ⚠️ 方法差异

> 七分类各自的完整输出格式与「必须遵守」条款见 references/文件提取规则.md 第十一节。

流程 5｜检索与回答（v2 四级引用优先级 + 四段结构）

四级引用优先级（强制）：
1. 第一：point.md 对应分类分区 — 优先沿用已沉淀的分析框架与逻辑路径，不每次重建框架；引用须标注 [来源：C001]
2. 第二：结合当下现状修正 — 在沉淀框架上结合最新数据/政策/动态推演，明确区分「沉淀逻辑的判断」与「基于现状的更新」；前提已变须指出变化及如何修正原结论
3. 第三：02-Areas / 01-Projects / 04-Skill 的 [沉淀] 卡片
4. 第四：03-Resources / 05-Archives 原始文档 — 仅用于事实核对/引用原文数据，不得直接作为观点结论

补充约束：
- 优先采用 status=已验证 / confidence 高的条目
- point.md 存在多条指向不同结论的逻辑时，并列展示并说明各自适用条件与分歧原因
- 不得编造 point.md 中不存在的逻辑链；若完全未覆盖，明确说明「知识库中暂无相关沉淀逻辑」，再基于常识回答并建议补充入库

回答结构（强制四段）：
1. 【沉淀逻辑】：先用 point.md 已有框架回答，标注来源序列号
2. 【现状修正】：结合当前最新情况，说明哪些逻辑仍成立、哪些需调整
3. 【综合判断】：沉淀逻辑 + 现状 → 最终判断
4. 【待观察变量 / 注意事项】：需持续跟踪的关键变量

各分类侧重点：
| 分类 | 回答侧重 |
|---|---|
| S 股票基金 | 业绩驱动 + 估值 + 催化剂 + 风险，最后给明确判断 |
| F 理财 | 配置逻辑 + 适用人群 + 执行步骤，不给具体产品推荐 |
| C 行业周期 | 周期定位 + 供需传导 + 拐点信号 |
| P 处世哲学 | 核心观点 + 适用场景 + 边界条件，不说教 |
| M 谈心营销 | 用户心理 + 可直接用的话术 + 避坑点 |
| E 宏观周期 | 周期定位 + 政策传导 + 大类资产配置建议 |
| K 行业知识 | 产业链结构 + 竞争格局 + 关键成功因素 |

流程 6｜图谱抽取（方案 1）

• 前提：文档含 ---图谱元数据开始--- / ---图谱元数据结束--- 区块
• 动作：套用固定系统提示词（见 references/图谱抽取器-系统提示词.md），只读该区块内的预置断言
• 禁止：从叙事区抽关系、脑补新关系、基于全文语义相似度生成临时关联
• 无区块 → 返回固定话术：【该文档无人工预定义显式图谱，不自动生成语义图谱】
• 问答映射字段：「创新点」→ 核心创新点；「局限」→ 局限性；「适用场景」→ 适用场景
• 边界提醒：这是「Prompt 约束 LLM 读预置断言」的折中方案，不是真正的图数据库检索

硬性约束（不可违反）

1. 不堆原文，只沉淀自己咀嚼过的知识
2. Schema 字段长期固定，不新增/改名；缺项标「未提及」
3. 元数据区一句一关系，不引申、不写评价
4. 实体命名前后一致
5. 图谱抽取不推断、不脑补
6. 回答必须先查 point.md，不得跳过第一优先级直接重建框架
7. 不得编造 point.md 中不存在的逻辑链
8. 沉淀卡片必须同步追加 point.md；素材与沉淀一律带 YAML 头

IMA 适配限制（避免误判）

• IMA 是全库向量索引，不支持按目录排除检索 → [素材] / [沉淀] 前缀是约束 AI 权重的约定，不是 IMA 的过滤机制
• IMA 不解析 YAML frontmatter，也不支持 Graphify / 双向链接 [[...]]；seq 等字段仅为约定与未来迁移服务
• point.md 建议在客户端置顶并调高检索权重，确保优先命中
• IMA 无删除、无移动、无真正覆盖接口 → 更新文档 = 重新上传 + 在客户端手动删旧版
• ⚠️ 检索接口的 folder_id 不能硬限定范围（语义相关性主导返回），靠引用优先级分流，不靠搜索范围

支付宝 AI 按量付费（A2M）接入规范

本 Skill 作为 Pay Skill 发布，必须遵循 A2M 协议。下文是与本 Skill 业务无关、但平台检测必需的通用章节；服务侧实现时严格按此协议接入。

1. 端点契约

服务实现需对外暴露以上 4 个端点；缺失任一项则会被 SkillHub 拒收。

2. 402 账单下发 + 携带凭证重试

首次调用本 Skill 时，服务端必须返回 HTTP 402 并在响应头携带账单：

HTTP/1.1 402 Payment Needed
Payment-Needed: trade_no=2026xxxxxxxxxx; serviceId=<YOUR_SERVICE_ID>; amount=10; unit=fen; pricing=0.1元/次; sign=<RSA2签名>

客户端必须根据 402 调 POST /pay 拿到 Payment-Proof 头，然后携带该头重试原业务请求：

POST /skill/<slug>
Headers:
  Payment-Proof: proof=<base64> trade_no=2026xxxxxxxxxx ts=... sign=<RSA2签名>
  X-Pay-Channel: alipay

服务端收到重试后验价（用支付宝公钥验 Payment-Proof 签名 + 校验金额/服务/未过期），通过则履约。

3. 履约确认

履约成功后立刻调 POST /ack 通知支付宝结算（异步即可，不阻塞业务返回）：

{
  "trade_no": "2026xxxxxxxxxx",
  "app_id": "<YOUR_APP_ID>",
  "status": "FULFILLED",
  "result_digest": "sha256:..."
}

4. 订单持久化与幂等

• trade_no 是全局唯一结算凭证，必须本地持久化（MySQL/Redis 均可，存「trade_no → 履约结果」）
• 收到 Payment-Proof 后先查重：同一 trade_no 已有结果则直接返回之前的结果，不重做业务（幂等）
• POST /ack 也需幂等：收到重复 ack 直接返回上次回执，避免重复结算
• 验价失败（金额不对、服务不对、签名不对、过期）拒绝履约并返回 403，不写订单

5. 依赖与凭据

代码需引入支付宝官方包并从环境变量读取凭据：

# Python 示例（任选其一）
# pip install alipay-sdk-python  或  alipay-aipay
from alipay.aipay.client import AipayClient
client = AipayClient(
    app_id=os.environ["ALIPAY_APP_ID"],                 # <YOUR_APP_ID>
    service_id=os.environ["ALIPAY_SERVICE_ID"],         # <YOUR_SERVICE_ID>
    app_private_key_path=os.environ["ALIPAY_APP_PRIV"], # 本机密钥文件路径
    alipay_public_key_path=os.environ["ALIPAY_PUB"],    # 支付宝公钥文件路径
    gateway="https://openapi.alipay.com/gateway.do",     # 生产网关
)

// Node.js
// npm install @alipay/aipay
import { AipayClient } from "@alipay/aipay";
const client = new AipayClient({
  appId: process.env.ALIPAY_APP_ID,
  serviceId: process.env.ALIPAY_SERVICE_ID,
  appPrivateKey: fs.readFileSync(process.env.ALIPAY_APP_PRIV, "utf8"),
  alipayPublicKey: fs.readFileSync(process.env.ALIPAY_PUB, "utf8"),
  gateway: "https://openapi.alipay.com/gateway.do",
});

6. 红线

• 绝不打款：本 Skill 不发起任何 alipay.trade.pay 类动作；只接收 trade_no 履约
• 不泄露私钥：app_private_key.pem 只放服务器本地环境变量，不进 Git、不进日志
• 不写死凭据：所有 app_id / service_id / key path 必须从环境变量读，便于多环境切换
• 必须幂等：trade_no 重复到达必须返回上次结果，绝不重复履行业务
• 超时与重试：调 POST /ack 失败按指数退避重试 3 次后写离线队列，不允许丢失 ack

7. 接入后验收（必跑）

1. 用生产 app_private_key 签一份 402 账单，验证客户端能正确拿到 trade_no
2. 模拟 Payment-Proof 重试，验证服务端验价通过 + 履约正常 + 写订单
3. 同一 trade_no 二次调用，验证直接返回上次结果（幂等）
4. 调 POST /ack 后台确认收到结算回执
5. 完整跑通 probe → pay → 业务调用 → complete → ack 5 步

8. 本 Skill 在 A2M 协议中的业务定位