渔芯 Agent 统一资料入站与查询标准
🚨 v3 现行标准(2026-09-13,覆盖以下全部 v1.x 流程):
- RKR scanner 已停机、RKR API 已停 →
staging_save.py/staging_query.py废用(staging_save 现行版写~/.hermes/staging/死区,scanner 永远看不到)- 资料一律直接 write_file/cp 到 ABCZ 四版块目录,权威索引 =
/Users/hua/rkr_staging/文档库/INDEX.md(v3,含旧→新路径映射、6 步判断流程、硬性禁区)- 同事 personal zone 新址 =
A-渔芯科技/A2-公司运营/部门空间/<名字>/- 全公司 10 份 AGENTS.md 已注入 v3 标准(2026-09-13);本文件以下 v1.x 内容(中转站/scanner/--source 白名单/陷阱 5-15)仅作历史坑位参考,执行时一律以 v3 为准
📦 核心原则(2026-08-03 华哥明确):
- 玉芬是全公司总负责人,向华哥负责。7 个 agent(毛豆/小宝/老莫/阿福/黑豆/学习助手/宽博士)都是玉芬的执行单元。 入库:直接
write_file/cp到~/rkr_staging/文档库/ABCZ 四版块指定目录(A1-水产RAS / A2-公司运营+部门空间 / B1B4 / C1-360行种子池(新项目 75 起号) / Z1-通用学科)。 查资料:直接/.hermes/profiles//cron/jobs.jsonls/grep -rl文档库目录。 权威索引:/Users/hua/rkr_staging/文档库/INDEX.md(v3,含旧→新路径映射 + 6 步采集判断流程 + 硬性禁区)。 旧顶层目录(1-通用知识/2-专业知识/3-公司项目资料/4-360行项目调研)已不存在,禁止重建;同事 personal zone=A2-公司运营/部门空间/<名字>/。 v3 下发全程(含幂等推送脚本与验证模式):references/v3-rollout-2026-09-13.md。 ⚠️ 陷阱 16(v3 下发实测):cron prompt 是"第二张路径藏匿面"——AGENTS.md 改完 ≠ 改完。同事 cron 的 prompt 里往往硬编码旧路径甚至旧写入指令,且 profile 级 cron 存放在 `(不在主库~/.hermes/cron/jobs.json)。实测(2026-09-13):zhenglishi 4 个 enabled 调研 cron 仍引用已不存在的文档库/4-360行项目调研/调研项目清单.md,且 research-all-day 写着"**用 staging_save.py,禁止直接写 ~/rkr_staging/**"——v3 之下这条指令会让每天 288 轮的调研笔记全部写进死区。**文档库任何结构调整后必做**:①grep -n "旧路径关键词" ~/.hermes/cron/jobs.json ~/.hermes/profiles//cron/jobs.json双库扫 ②逐条改写 prompt 内路径+反转危险指令 ③JSON 备份.bak-<日期>` 后写回 ④跑一次受影响 cron 验证(如往 62 号项目目录写删一个自检文件)。research_pointer 类 state 文件若只存项目名/相对名则不受重组影响,改前先确认。 下方 v1.5 时代内容保留作历史参考——其中所有 staging_save/staging_query 调用示例*已失效,勿再使用。
📦 核心原则(2026-08-03 华哥明确):
- 玉芬是全公司总负责人,向华哥负责。7 个 agent(毛豆/小宝/老莫/阿福/黑豆/学习助手/宽博士)都是玉芬的执行单元。
- 3-公司项目资料/ 是工作空间,不是归档层 — 业务结果性报告直接
cp/mv/write_file放这里(玉芬授权范围)- 1-通用知识/ 2-专业知识/ 4-360行项目调研/ 仍是归档层 — 走 staging 中转站,scanner 自动分类
- 写:业务结果性报告直接放工作空间(玉芬授权);归档层资料走
staging_save.py中转站- 读:所有 agent 调资料 → 统一调用
staging_query.py→ RKR API- 决策:5 个同事无版主决策权(分类/整理/清理/合并/归档/淘汰权归玉芬)
架构(端到端流程)
Agent 调研/生成(归档层:1/2/4)
↓ staging_save.py
~/rkr_staging/文档中转站/<子目录>/<日期>_<uuid>_<标题>.md
↓ RKR local_staging_scanner.py(每 60 秒扫一次)
~/rkr_staging/文档库/<分类>/(自动分类:1-通用知识/2-专业知识/4-360行)
↓ RKR process_shared_document(异步向量化 + 知识图谱)
RKR PostgreSQL + pgvector(永久存储)
↓ staging_query.py (RKR API)
Agent 调资料(知识检索 / 文档列表 / 关键词搜索)
Agent 调研/生成(工作空间:3-公司项目资料/)
↓ 直接 cp / mv / write_file
~/rkr_staging/文档库/3-公司项目资料/<子目录>/ ← 自由操作,新建/修改/移动/删除
关键事实:
- RKR
DEFAULT_STAGING_DIR = ~/rkr_staging/文档中转站/(已默认) - scanner 60 秒扫一次,发现新文件就处理
- 处理完自动删除中转站原文件(这是 RKR 设计行为,正常)
- 中转站 ≠ 文档库;中转站是 staging,文档库是归档层 + 工作空间两层
2 层 + 1 工作空间架构(2026-08-03 华哥明确)
~/rkr_staging/文档库/ 下面分两层 + 一个工作空间,每层有严格的"谁写、谁读"规则:
~/rkr_staging/文档库/
├── 1-通用知识/ ← Layer 1:【RKR 归档层,只读】跨领域通识(scanner 分类)
├── 2-专业知识/ ← Layer 1:【RKR 归档层,只读】RAS/水产专业(scanner 分类)
├── 4-360行项目调研/ ← Layer 1:【RKR 归档层,只读】新行业调研占位(scanner 分类)
│
├── 3-公司项目资料/ ← Workspace:【可写工作空间,自由操作】(2026-08-03 华哥明确)
│ ├── 301-智能体/ ← 5 个同事 agent 的 personal zone
│ │ ├── 毛豆-产品交付/
│ │ ├── 小宝-商务运营/
│ │ ├── 老莫-技术运维/
│ │ ├── 阿福-客服/
│ │ ├── 黑-行政财务法务/ (4K 空,待合并)
│ │ └── 黑豆-行政财务法务/
│ ├── 303-竞品库/ ← 毛豆主理
│ ├── 304-公司运营/ ← 16 个子目录(其中 4 个空白待激活)
│ │
│ ├── 302-数据与素材库/ ← 5.7G 共享二进制素材(需协调)
│ ├── antigravity-awesome-skills/ ← GitHub mirror 仓库(RKR 资源)
│ ├── awesome-claude-code/ ← GitHub mirror 仓库(RKR 资源)
│ ├── cad_samples/ ← CAD 样本(RKR 资源)
│ ├── material_library/ ← 材料库(RKR 资源)
│ ├── mech_drawing/ ← 机械图纸(RKR 资源)
│ └── ... 其他 RKR 资源
│
├── cleaned/ ← RKR 清洗临时 .txt(244 个,**严禁碰**)
└── 通用知识库/ ← RKR 索引库 .md 快照(26686 个,**严禁 ls / 引用文件路径**)
工作空间使用规则(2026-08-03 玉芬统一分配):
玉芬是全公司总负责人,所有版块管理由玉芬统一决策。7 个 agent 是玉芬的执行单元,各自负责配对版块的日常运营,版主决策权归玉芬。
| Agent | 业务 | 配对版块(玉芬指定) | 写读方式 |
|---|---|---|---|
| 玉芬 | 全公司总负责人 | 所有版块(统一决策) | 玉芬向华哥负责 |
| 毛豆 | 产品交付 / AI 出 CAD / 3D 工程 | 2-专业知识/(RAS) + 303-竞品库/ + 304/产品研发全链条/ | 报告直接放工作空间;RAS 走中转站 |
| 小宝 | 销售 / 商务运营 / 自媒体 | 304/销售与市场营销/ + 304/市场推广/ | 销售话术/案例直接放工作空间 |
| 老莫 | 技术运维 / 知识库 / 测试 | 老莫 personal zone + freecad-automation/ + 304/客户服务与运维/ | 运维 SOP 直接放;测试报告直接放 |
| 阿福 | 客服 / 演示 / 用户反馈 | 阿福 personal zone + EDAI自动审批测试/ + 4-360行项目调研/(主理) + 304/客户服务与运维/ | FAQ 直接放;新行业调研走 4-360行 |
| 黑豆 | 行政 / 财务 / 法务 / 合规 | 黑豆 personal zone + 304/法规标准与认证/HR/财务/知识产权/ | 合同/制度直接放;政策走 1-通用知识/ |
| 学习助手 | 资料采集 / 调研 | 1-通用知识/(主理) + zhenglishi personal zone | 全部走 staging 中转站 |
| 宽博士 | 量化研究 | quant personal zone + 1-通用知识/2.6 量化/ | 量化报告直接放 quant/;方法论走 1-通用知识/2.6 |
协调冲突规则:
- 跨 agent 版块冲突(例如毛豆的竞品 vs 小宝的销售话术引用同一竞品)→ 玉芬裁决
- 5 个同事的产出 → 默认送玉芬审 → 玉芬决定是否合并/淘汰/调整
- 玉芬向华哥负责,华哥只看玉芬的交付
所有同事都不能动:
1-通用知识/2-专业知识/4-360行项目调研/(RKR 归档层,新资料走中转站)cleaned/通用知识库/(RKR 内部产物)es_data/minio_data/pgdata/redis_data/rkr_backup.dump(RKR 基础设施)3-公司项目资料/下的 RKR 资源(antigravity-awesome-skills/cad_samples/material_library/mech_drawing/等)
核心心法(快速对照表):
| 触发场景 | 写到哪 | 用什么 |
|---|---|---|
| 写一份"竞品调研" / "行业分析" / "通用知识" / "RAS 专业知识" | Layer 1 中转站 → scanner 自动归类到 1-通用/ 2-专业/ 4-360行/ |
staging_save.py --source research |
| 写一份"销售话术" / "客服 SOP" / "技术报告" / "合同模板" / "制度文件" | Workspace 3-公司项目资料/(直接放) |
cp / mv / write_file |
| 写一个已收敛的专题页(HW-001 设备页、BP 调研、FAQ 库) | 3-公司项目资料/301-智能体/<agent>/<专题名>/ |
write_file 直接写(沉淀) |
| 读"养殖池循环水设计"相关资料 | RKR API(从 pgvector 检索) | staging_query.py search |
| 调试时审计文档库 | 文件系统(只读,不写) | ls / du |
| 批量 mirror GitHub 仓库 | Layer 1 中转站 yuxin-skills-YYYYMMDD/ |
sync_yuxin_skills_to_staging.sh |
| 历史资料(散落在 Desktop/profiles) | Layer 1 中转站 migration_YYYYMMDD/ |
migrate_agent_artifacts.py --execute |
4 个有效归档目录分类判断(2026-08-03 玉芬固化)
文档库只有 4 个有效顶层目录,任何调研/报告写入前必须先归类:
| 顺序 | 判断条件 | 目录 | 类型 | 写入方式 |
|---|---|---|---|---|
| 1 | 渔芯具体业务的结果性报告(竞品分析/产品方案/技术报告/合同/SOP/话术/FAQ) | 3-公司项目资料/ |
🟢 工作空间 | write_file / cp / mv 直接放 |
| 2 | 水产养殖 / RAS 专业知识 | 2-专业知识/ |
🟢 归档层 | 走 staging_save.py 中转站 |
| 3 | 跨领域通用知识(AI/工程/管理/创意/量化/设计/仿真/OPC/法律/管理/经济/政治/学术) | 1-通用知识/ |
🟢 归档层 | 走 staging_save.py 中转站 |
| 4 | 暂时无法确定归属的新行业、新项目调研 | 4-360行项目调研/ |
🟢 归档层 | 走 staging_save.py 中转站 |
判断口诀(优先级从高到低):
- "是渔芯业务的结果性报告吗?" 是 → 直接放
3-公司项目资料/工作空间(write_file/cp/mv) - "是 RAS / 水产专业知识吗?" 是 → 走中转站 →
2-专业知识/ - "是跨行业通用方法吗?" 是 → 走中转站 →
1-通用知识/ - "是新行业探索但暂时无法归类?" 是 → 走中转站 →
4-360行项目调研/
用户硬性约束(2026-08-03 华哥明示,仅适用于归档层 1/2/4):
- ❌ 不能
cp ~/rkr_staging/文档库/1-通用知识/...md拷贝归档层文件出来(归档层是 scanner 产物,不能动) - ❌ 不能
mv ~/rkr_staging/文档库/1-通用知识/...md移动归档层文件 - ❌ 不能
rm ~/rkr_staging/文档库/1-通用知识/...md删除归档层文件 - ❌ 不能在归档层(1/2/4)子目录下
write_file新建文件(RKR scanner 不会扫这里,索引不上) - ✅ 可以在
3-公司项目资料/工作空间下write_file新建/修改/移动/删除自己负责的子目录 - ✅ 可以
ls/du/cat读文档库任何子目录(用于审计) - ✅ 可以
read_file读文档库任何文件(用于理解归档结构)
⚠️ v1.3.0 关键警告:
3-公司项目资料/是工作空间不是归档层,直接 write_file 是对的;但绝不能把1-通用知识/2-专业知识/4-360行项目调研/也当作可写工作空间(常见误读,本 skill v1.0–v1.2 曾混淆)。华哥 2026-08-03 明确:3-公司项目资料/是为同事业务结果性报告准备的"留给大家的工作空间,可以自由操作",归档层仍是 RKR scanner 管理的只读分类层。
5 同事 AGENTS.md 下发流程(2026-08-03 玉芬建立)
当路径 SOP / 工具规范 / agent 工作流发生变更,需要同步到 5 个同事(毛豆/小宝/老莫/阿福/黑豆),完整流程:
- 更新本 skill(
staging-helper/SKILL.md+templates/agent-workspace-sop.md) - 写 5 份
AGENTS.md到~/.hermes/profiles/<agent>/AGENTS.md(Hermes 启动自动加载,不在文档库) - 入库规范文档:
staging_save.py --source yuxin --agent yuxin --tag 工作目录/路径SOP/Agent规范(60 秒后 scanner 归类) - 飞书回执给华哥:列出 5 份 AGENTS.md 路径 + 入库规范文档路径 + 核心规则摘要
详细模板见 templates/agent-workspace-sop.md;rollout 流程的历史决策/坑见 references/agent-rollout-procedure.md(2026-08-03 建立)。
目录全景参考:见 references/document-library-layout.md(2026-08-03 实测)
agent personal zone 规则:见 references/agent-personal-zone.md
使用方法
1. 写资料(agent 调研/生成完调用)
# 命令行(⚠️ 2026-09-06 实测:当前版本**不支持 --tag/--subdir**,传了直接 argparse 报 unrecognized arguments;
# 只收 --title/--content/--source/--agent/--target。标签语义放标题或入库后手补 .meta.json)
# ⚠️ 路径用绝对路径,防 profile HOME 劫持(陷阱5)
python3 /Users/hua/.hermes/scripts/staging_save.py \
--title "养殖池循环水设计调研" \
--content "$(cat research.md)" \
--source research \
--agent maodou
# Python API(⚠️ `agent=` 必须是顶层 kwarg,不能放 meta 里 — 见陷阱 14)
from staging_save import stage
stage(
title="养殖池循环水设计调研",
content="# ... markdown ...",
source="research",
agent="maodou", # ← 顶层必传,放 meta 里会被静默吞掉
tags=["养殖池", "循环水"],
)
⚠️ 常见错误:把
agent写进meta={}字典里(meta={"agent": "maodou", ...})。stage()签名里agent是顶层 kwarg,写在 meta 里会被静默忽略,输出Agent: default,文件仍入站但路由失效。详见陷阱 14。
参数说明:
--title(必填): 资料标题--content(必填): Markdown 内容(@file.md从文件读)--source: research(调研) / generated(生成) / report(报告) / raw(原始) / yuxin(玉芬整理) / findera(寻元)
⚠️
--source是严格白名单(research/generated/report/raw/yuxin/findera/default,共 7 个固定值)。派单文件 / 协作通知里若写--source quant、--source maodou等非法值,argparse 会直接拒绝(error: argument --source: invalid choice),任务当场失败。遇到此类派单(2026-08-30 老莫协助宽博士量化因子库实战踩坑):改用语义最接近的合法值(量化调研 →research),并用--subdir 07-量化因子之类自定义子目录做路由标识,最后在 kanban 评论里记录这一偏差供下游知悉。
--source 合法值精确枚举(必背):
research # 调研(行业/竞品/学术)
generated # 生成(AI 输出/草稿)
report # 报告(已完成交付物)
raw # 原始数据
yuxin # 玉芬整理
findera # 寻元采集
default # 兜底(不推荐主动用)
任何不在上表的字符串(如 quant / maodou / analysis / compliance)都会被 argparse 拒绝。详见陷阱 15。
--agent: agent 名字(默认$HERMES_AGENT)--tag: 标签(可多次)--meta: 额外元数据key=value(可多次)
文件落地格式:
~/rkr_staging/文档中转站/01-调研资料/20260730_180040_b643d516_养殖池循环水设计调研.md
~/rkr_staging/文档中转站/01-调研资料/20260730_180040_b643d516_养殖池循环水设计调研.md.meta.json
子目录自动按 source 分类(01-调研资料 / 02-生成内容 / 03-调研报告 / 04-原始资料 / 05-玉芬整理 / 06-寻元采集)。
2. 读资料(agent 调资料时调用)
# 文档库总览
python3 ~/.hermes/scripts/staging_query.py stats
# 列出"知识文库"前 20 个
python3 ~/.hermes/scripts/staging_query.py list --lib knowledge --limit 20
# 关键词搜
python3 ~/.hermes/scripts/staging_query.py search --query "养殖池" --limit 10
# 列出所有 RKR 项目
python3 ~/.hermes/scripts/staging_query.py projects
Python API:
from staging_query import cmd_list, cmd_search, _http, get_token
import json
token = get_token()
# 直接调 RKR API
data = _http("GET", "/api/v1/library/knowledge?search=养殖&page_size=5", token=token)
print(json.dumps(data, ensure_ascii=False, indent=2))
各 agent 接入建议
| Agent | 调研/生成场景 | 接入方式 |
|---|---|---|
| 玉芬 (yuxin) | 整理资料、归档笔记 | staging_save.py --agent yuxin --source yuxin |
| 毛豆 (maodou) | 产品调研、技术分析 | staging_save.py --agent maodou --source research |
| 阿福 (afu) | 客服话术、答疑资料 | staging_save.py --agent afu --source generated |
| 黑豆 (heidou) | 行政文档、合规资料 | staging_save.py --agent heidou --source report |
| 老莫 (laomo) | 知识库整理、测试报告 | staging_save.py --agent laomo --source yuxin |
| 小宝 (xiaobao) | 销售方法论、内容脚本 | staging_save.py --agent xiaobao --source generated |
| 整理师 (zhenglishi) | 华哥知识库整理 | staging_save.py --agent zhenglishi --source yuxin |
| 宽博士 (quant) | 量化研究、报告 | staging_save.py --agent quant --source report |
| FindEra (寻元) | 域资料采集 | 现有 rkr_sync.py 走 RKR API(保留) |
常见陷阱
⚠️ 陷阱 0(v1.3.0 新增):把整个文档库当归档层 — 常见误读
症状:agent 看到"文档库"就以为全部是 RKR scanner 自动分类的归档产物,不敢在 3-公司项目资料/ 下 write_file,把所有同事报告都走 staging 中转站。
根因:v1.0–v1.2 的 SKILL 把整个 ~/rkr_staging/文档库/ 描述为"只读归档层",没有区分 3-公司项目资料/。这是误读 — 华哥 2026-08-03 明确:"3-公司项目资料 是留给大家的工作空间,可以自由操作"。
正确理解(2 层 + 1 工作空间):
- 🟢 归档层(只读,走中转站):
1-通用知识/2-专业知识/4-360行项目调研/(RKR scanner 自动分类) - 🟢 工作空间(直接 write_file):
3-公司项目资料/(同事放"结果性报告":竞品/产品/技术/合同/SOP/话术/FAQ)
典型错例:
# ❌ v1.2 风格的"安全"做法 — 把竞品报告塞中转站(没必要,且会失去 RKR 直接索引)
stage(title="Hydrotech-2026 竞品分析", content=..., source="research", agent="maodou")
# 等 60 秒 → scanner 归类 → 同事想看还要 staging_query.py 搜
# ✅ v1.3.0 正确做法:直接放工作空间
Path("/Users/hua/rkr_staging/文档库/3-公司项目资料/303-竞品库/Hydrotech-2026.md").write_text(content)
# 立刻可读,scanner 会顺便索引(双保险)
速查表:
| 资料类型 | 正确位置 | 工具 |
|---|---|---|
| 竞品分析报告 | 3-公司项目资料/303-竞品库/ |
write_file |
| 产品方案 / 技术报告 | 3-公司项目资料/301-智能体/<agent>/ |
write_file |
| 销售话术 / FAQ | 3-公司项目资料/304-公司运营/销售与市场营销/ |
write_file |
| 合同模板 / 合规清单 | 3-公司项目资料/301-智能体/heidou/knowledge/ |
write_file |
| 通用知识调研 | 中转站 → scanner → 1-通用知识/ |
staging_save.py |
| RAS 专业调研 | 中转站 → scanner → 2-专业知识/ |
staging_save.py |
| 新行业调研 | 中转站 → scanner → 4-360行项目调研/ |
staging_save.py |
❌ 错误 1: 直接写归档层(1-通用知识/2-专业知识/4-360行)
# ❌ 错误:直接写"通用知识"
Path("~/rkr_staging/文档库/1-通用知识/我的文档.md").write_text(content)
# 问题:scanner 不会扫这里(归档层是 scanner 输出),文档不会被处理/索引
# ✅ 正确:写"中转站"让 scanner 自动处理
stage(title="我的文档", content=content, source="research", agent="xxx")
# ✅ 业务结果性报告:直接放工作空间 3-公司项目资料/
Path("~/rkr_staging/文档库/3-公司项目资料/301-智能体/毛豆-产品交付/我的报告.md").write_text(content)
❌ 错误 2: 写完资料后 60 秒内就检查"文档库"
# ❌ 错误:写完立刻检查
stage(title="...", content="...")
sleep 5
ls ~/rkr_staging/文档库/ # 还没出现!scanner 每 60 秒扫一次
# ✅ 正确:用 staging_query.py 通过 RKR API 查(不等)
python3 ~/.hermes/scripts/staging_query.py list --lib knowledge --limit 5
❌ 错误 3: 把 staging_save 的输出文件当"永久"文件
staging_save 写入的文件 60 秒内会被 scanner 删除(这是 RKR 正常行为)。
要"永久保留"原始内容,请用 --meta 写进 .meta.json,或自己备份。
❌ 错误 4: 用 ~/rkr_staging/文档库/ 做路径硬编码
- 不同 agent 的 home 路径可能不同
- 用户可能改 rkr_staging 位置
- 永远用 staging_save / staging_query 抽象
⚠️ 陷阱 5: Hermes profile envvar 劫持 $HOME(关键)
任何在 Hermes 子 profile(afu/maodou/laomo 等)下启动的脚本,$HOME 都会被改写成 ~/.hermes/profiles/<name>/home/。结果:
# ❌ 错误:脚本以为 home 是 /Users/hua,实际是 ~/.hermes/profiles/afu/home
Path.home() / "rkr_staging" # → ~/.hermes/profiles/afu/home/rkr_staging(不存在!)
Path("~/rkr_staging/...") # → ~/.hermes/profiles/afu/home/rkr_staging/...(不存在!)
症状:staging_save.py 写入了一个根本不存在的目录,scanner 看不到,ls 也找不到。
修复(staging_save.py v1.0.0 已修):用 os.path.expanduser("~/rkr_staging/文档中转站") 仍会错,要硬编码:
STAGING_DIR = Path("/Users/hua/rkr_staging/文档中转站") # 不要用 Path.home() 或 ~/
华哥本机是
/Users/hua,未来换用户 / 多用户部署时此常量要参数化。
⚠️ 2026-09-06 玉芬复现:即使调用路径用绝对路径
/Users/hua/.hermes/scripts/staging_save.py,脚本内部的落盘目录仍可能解析到 profile home(输出已保存到 /Users/hua/.hermes/profiles/zhenglishi/home/.hermes/staging/...,scanner 看不到)。另:当前版本脚本不支持--tag参数(error: unrecognized arguments: --tag),只收--title/--content/--source/--agent/--target。修复 SOP:脚本保存后检查输出路径,若含profiles/,手动cp文件到/Users/hua/rkr_staging/文档中转站/01-调研资料/并手写同名.md.meta.json(含 title/source/agent/tags/original_path),60 秒内 scanner 会正常入库。
⚠️ 2026-08-24 审计复现:毛豆(08-17)+ 宽博士/量化(08-15)先后踩同一坑,都写进了字面量
~/Desktop/知识库/RAS仿真技术调研/目录:
- 毛豆:
3-公司项目资料/301-智能体/毛豆-产品交付/workspace/~/Desktop/...(玉芬已清理,移到workspace/RAS仿真技术调研/)- 宽博士:
1-公共知识/114-项目开发与调研/8-量化研究/~/Desktop/...(归档层,待宽博士自修) 教训:陷阱 5 的"用绝对路径"SOP 未传达到位,两个 agent 的调研脚本都在用~/相对路径。排查方法:find ~/rkr_staging/文档库 -type d -name '~'可快速定位所有残留字面量~目录。
⚠️ 陷阱 6: 浏览器缓存可能让你以为有某个 RKR 功能
症状:用户说"我看到 RKR 有『技能仓库』模块",但代码里根本没有 —— 浏览器渲染的是旧 dist / 缓存页面。
诊断:
# 1. 直接看 RKR 源码菜单(前 11 个菜单一般是稳定基线)
grep -E 'label:' /Users/hua/6-产品研发/01-RKR知识库/frontend/src/components/layout/Sidebar.tsx
# 2. 看 docker 容器内 frontend 镜像版本
docker exec rkr-frontend cat /app/package.json | python3 -c "import sys,json;print(json.load(sys.stdin).get('version'))"
# 3. 比对源码 git log(看是不是有未提交的本地修改)
cd /Users/hua/6-产品研发/01-RKR知识库 && git status
⚠️ Vite dev server 模式(5173 端口)会直接读源码,所以源码更新即生效;但访问页面走的是缓存(ctrl+shift+R 强制刷新)。
⚠️ 陷阱 7: RKR 项目源码路径有两种,Desktop 那个是错的
# ❌ 错的(CLAUDE.md 提到的,但 iCloud 没同步时是空的)
~/Desktop/渔芯科技/6-产品研发/01-RKR知识库/ # ← 实际不存在或为空
# ✅ 真的(华哥手指定)
/Users/hua/6-产品研发/01-RKR知识库/ # ← 全部 RKR 源码 + docker-compose
之前踩过坑:ls ~/Desktop/渔芯科技/6-产品研发/ 看到一堆乱七八糟,真实 RKR 项目在 /Users/hua/6-产品研发/01-RKR知识库/。永远用绝对路径。
⚠️ 陷阱 8: 批量文件系统 mirror ≠ 批量入库;用 API 才稳
症状:rsync 把 833 个 .md 镜像到 ~/rkr_staging/文档中转站/,scanner 跑了,但只入库了 ~8 个文档(41642 → 41650)。
根因:scanner 对纯 .md 文件和有 .meta.json 配套的文件处理策略不同:
- 有
.meta.json配套 → 元数据完整 → 顺利入库 - 纯 .md(无元数据)→ 可能入 staging project 后还需 LLM 分类,慢且命中率低
修复:
- 单文件 / 少量资料 → 用
staging_save.py(自动写 .meta.json) - 批量大量资料(如 GitHub 全仓库 mirror)→ 用 RKR upload API:
for fmd in files: requests.post("http://localhost:8000/api/v1/staging/upload", headers={"X-API-Key": "rkr_..."}, json={"title": ..., "content": fmd.read_text(), "project_id": "a7a325c9-..."})
❌ 错误 9: 业务结果性报告直接放 workspace 而不放 3-公司项目资料/(2026-08-03 规则变化)
# ❌ 错误:把"竞品报告"丢到 workspace 当成草稿(2026-08-03 之前习惯)
Path("/Users/hua/rkr_staging/文档库/3-公司项目资料/301-智能体/毛豆-产品交付/workspace/竞品分析/Hydrotech-2026.md").write_text(content)
# 问题 1: 其他 agent(老莫、阿福、小宝)用 staging_query.py 搜不到(workspace 是临时区)
# 问题 2: 同事 agent 之间的知识不可共享
# 问题 3: 这不是"草稿"了,这是"结果性报告",应该放 3-公司项目资料/ 工作空间
# ✅ 正确(2026-08-03 起):竞品报告直接放 3-公司项目资料/ 工作空间
Path("/Users/hua/rkr_staging/文档库/3-公司项目资料/303-竞品库/Hydrotech-2026.md").write_text(content)
# 或放到自己 personal zone
Path("/Users/hua/rkr_staging/文档库/3-公司项目资料/301-智能体/毛豆-产品交付/竞品分析/Hydrotech-2026.md").write_text(content)
# 这两份都能被 RKR scanner 顺便索引(虽然不是必需的,主要是工作空间)
判断标准(2026-08-03 新规则):
- 业务结果性报告(竞品分析/产品方案/技术报告/合同/制度/话术/FAQ) → 直接放
3-公司项目资料/工作空间(write_file/cp/mv) - 通用知识调研稿 / RAS 专业调研稿 / 新行业调研 → 走
staging_save.py中转站(让 scanner 自动归类到 1-通用/2-专业/4-360行) - 已收敛的专题页(
HW-001_滚筒微滤机/、BP调研/、RAS设备销售/) → 放301-智能体/<agent>/下,本身就是工作空间的一部分 - 工具产物(.json/.csv/.zip/中间计算结果) → 放
workspace/,不进 RKR - 过程稿 / 草稿 → 放
workspace/,完成后再决定走中转站还是放工作空间
快速判断口诀:
- "是渔芯业务的结果性报告吗?" 是 → 放
3-公司项目资料/工作空间 - "以后要搜得到吗?是归档层知识(1/2/4)吗?" 是 → 走中转站
- "还是草稿/工具产物?" 是 → 放
workspace/
实际踩过的违例(2026-08-03 扫描发现):
小宝-商务运营/workspace/竞品分析/下若干 .md 调研稿 → 孤儿文档毛豆-产品交付/HW-001_滚筒微滤机/等专题页中混有过程稿(应拆出走中转站)1-通用知识/1.9 大模型/、1.9 ai爬虫技术/等目录下文件名混乱无 meta.json(早期 agent 直接cp到文档库遗留)
⚠️ 陷阱 10: 不要把 通用知识库/ 26686 个 .md 或 cleaned/ 244 个 .txt 当"知识源"
症状:agent 想"参考" ~/rkr_staging/文档库/通用知识库/00-总索引.md 这种文件来引用知识。
问题:
通用知识库/是 RKR 索引库的导出快照,每次重建会被覆盖,文件路径不稳定cleaned/是 RKR LLM 清洗中间产物,下次 RKR 重建会被清空- 任何 agent 把这些文件的绝对路径写进自己的 MEMORY.md / 知识引用 → 重建后全失效
正确:
- 引用知识 → 走
staging_query.py search(返回的是 RKR 内部 id,稳定) - 不要把
~/rkr_staging/文档库/通用知识库/xxx.md的路径硬编码到任何长期文件
⚠️ 陷阱 11: 302-数据与素材库/ 是二进制仓库,不走 RKR
说明:3D模型/(3.9G)、图片/(893M)、视频/(220M)、工程图纸/(639M)、材料库/(1.6G)、mech_drawing/(4.3G) 都是二进制素材,RKR 索引不了。
- 写入:直接
cp/mv(不走 staging) - 引用:用相对路径(在文档库内部),或对象存储 URL
- 不要试图把这些目录 mirror 到中转站(9.5G 中转站会被塞爆)
⚠️ 陷阱 14(2026-08-26 整理师心跳实测):stage(agent=...) 必须是顶层 kwarg,放进 meta={} 里会被静默吞掉
症状:调用 stage() 后输出 Agent: default | Source: research,而不是你期望的 agent 名。文件确实入站成功(中转站有文件、.meta.json 写好),但 agent 字段错了 → scanner 后续的路由/分类规则全失效,文件最终落到默认分类。
根因(staging_save.py 源码):
def stage(
title: str,
content: str,
source: str = "research",
agent: Optional[str] = None, # ← 这是顶层 kwarg
tags: Optional[list] = None,
subdir: Optional[str] = None,
meta: Optional[dict] = None, # ← agent 写进 meta 字典 = 被忽略
):
if not agent:
agent = os.environ.get("HERMES_AGENT", "default") # ← fallback 到 env var 或 default
meta 字典里的 "agent": "xxx" 不会回填到顶层 agent 参数,也不会被任何代码读出来 → 静默丢失。
实测复现(2026-08-26 09:01):
# ❌ 错误:agent 写进 meta(静默丢失 → 输出 Agent: default)
result = stage(
title="...",
content=...,
tags=[...],
meta={"agent": "zhenglishi", "scanner_status": "..."}, # ← agent 字段被忽略
)
# 输出: ✅ 已入站: ... | Agent: default | Source: research
# ✅ 正确:agent 作为顶层 kwarg(显式传)
result = stage(
title="...",
content=...,
source="research",
agent="zhenglishi", # ← 顶层 kwarg
subdir="01-调研资料",
tags=[...],
meta={"scanner_status": "..."}, # meta 只放额外元数据,不放 agent
)
# 输出: ✅ 已入站: ... | Agent: zhenglishi | Source: research
防御性写法(os.environ 兜底 + 顶层 kwarg 双保险):
import os
os.environ["HERMES_AGENT"] = "zhenglishi" # 防 cron 启动时没设 env
from staging_save import stage
stage(title=..., content=..., source="research", agent="zhenglishi", ...)
为什么 meta 里还写 agent 字段:不影响功能(scanner 走顶层 agent),但方便后续审计/反向追溯(从 .meta.json 反查当时调用者意图)。保留无害,删除也行。
与已有陷阱的关系:
- 陷阱 13(workspace/knowledge 三路径分离):说的是落盘路径问题
- 陷阱 14(agent 静默丢失):说的是调用签名问题
- 两个都触发"入站成功但行为不对",但前者是文件位置错,后者是文件元数据错
⚠️ 陷阱 13: agent personal zone 内的 workspace/knowledge/ ≠ staging 中转站 ≠ scanner 自动归档目标(2026-08-24 实战)
症状:agent 用 staging_save.py 写入了一份合同模板 v1.1,scanner 在 60 秒内确实把中转站原文件处理掉了,但审计脚本 grep 的不是 3-公司项目资料/301-智能体/<agent>/workspace/knowledge/——4 小时后 cron 审计仍报"P0,109 天未修订"。
根因(三层路径混在一起):
- staging 中转站 =
~/rkr_staging/文档中转站/02-生成内容/(60 秒后被 scanner 自动删) - scanner 自动归档目标 =
~/rkr_staging/文档库/3-公司项目资料/301-智能体/<agent>/knowledge/(业务报告的"标准"落地路径) - agent 个人工作区 =
<profile_home>/workspace/knowledge/或~/rkr_staging/文档库/3-公司项目资料/301-智能体/<agent>/workspace/knowledge/(审计脚本实际访问的路径——很多合同模板/政策核验脚本KNOW_DIR都硬编码这里)
关键事实:
- staging_save.py 不保证把文件 mirror 到 agent 的
workspace/knowledge/(它是中转站路径,与 agent personal zone 的 workspace 是两个独立目录) - scanner 自动归档到
3-公司项目资料/301-智能体/<agent>/knowledge/也不保证同步到<agent>/workspace/knowledge/ - 审计脚本
grep -E "关键词" $KNOW_DIR通常指向workspace/knowledge/(因为这才是合同模板等"高频访问"资产的真实存放点) - staging 写入 ≠ workspace 归档 ≠ audit 脚本可见——三步互相独立,缺一不可
反面案例(2026-08-23 20:33 → 08-24 00:35):
- 20:33 cron
staging_save写入项目合作协议 v1.1 到02-生成内容/(✓) - 20:33 scanner 处理中转站,自动归档到
3-公司项目资料/301-智能体/黑豆-行政财务法务/knowledge/(可能成功,但路径不同) - 20:33-00:35 之间,审计脚本 grep
<agent>/workspace/knowledge/仍显示 v1.0(0 命中,109 天) - 00:35 才手动
cp 02-生成内容/<v1.1>.md <agent>/workspace/knowledge/<v1.1>.md兜底 - 4 小时错配期间,审计脚本误报"P0 待承接",导致资源错估 + 后续承接优先级判断偏差
正确做法(写入双路径自检 SOP):
# 1. staging 写入
python3 ~/.hermes/scripts/staging_save.py \
--title "<标题>" \
--content @<file>.md \
--source report --agent <自己>
# 2. ⚠️ 必须再 cp 一份到 workspace/knowledge/(若审计脚本 grep 那里)
cp ~/rkr_staging/文档中转站/02-生成内容/<file>.md \
~/rkr_staging/文档库/3-公司项目资料/301-智能体/<agent>/workspace/knowledge/<file>.md
# 3. ⚠️ 必须再 cp 一份到 3-公司项目资料 knowledge/(若其他 agent 要 RKR 索引)
cp ~/rkr_staging/文档中转站/02-生成内容/<file>.md \
~/rkr_staging/文档库/3-公司项目资料/301-智能体/<agent>/knowledge/<file>.md
# 4. 双路径落地自检(grep workspace/knowledge/)
grep -c -E "<关键词>" ~/rkr_staging/文档库/3-公司项目资料/301-智能体/<agent>/workspace/knowledge/<file>.md
# 输出 > 0 才算真正落地
# 5. 在 evolution report 明确"双路径落地状态"
# ✅ 02-生成内容 + workspace/knowledge + knowledge 三路径同步
判断标准:
| 落地路径 | 谁读 | 写入方式 |
|---|---|---|
~/rkr_staging/文档中转站/02-生成内容/ |
scanner | staging_save.py(60 秒后被删) |
3-公司项目资料/301-智能体/<agent>/knowledge/ |
RKR 索引 + 其他 agent | scanner 自动 / 手动 cp |
3-公司项目资料/301-智能体/<agent>/workspace/knowledge/ |
本 agent 审计脚本 | 必须手动 cp |
关键纪律:
staging_save.py写入 ≠ agent 可在 workspace 看到- agent 写入后,必须同时 cp 到
workspace/knowledge/(本 agent 审计路径) - 如果业务上要让其他 agent 也能搜到,再加 cp 到
knowledge/(RKR 索引路径) - 进化报告必须明确"双路径/三路径落地状态",否则下次 cron 无法判断是否漏归档
workspace/knowledge/是 agent personal zone 的子目录,不是 RKR 归档层,直接 cp 不违反3-公司项目资料/工作空间规则
例外:如果该 agent 的审计脚本 KNOW_DIR 指向 3-公司项目资料/301-智能体/<agent>/knowledge/(而非 workspace/knowledge/),则 cp 到那一个即可——先看审计脚本再决定 cp 哪个。
⚠️ 陷阱 15: --source 非法值踩坑 + 派单模板示例错误(2026-08-30 黑豆 / 老莫 / 小宝 / 阿福 / 毛豆 5 同事协作实测)
症状:跑 python3 ~/.hermes/scripts/staging_save.py --source quant --agent heidou 直接报错:
usage: staging_save.py [-h] --title TITLE [--content CONTENT]
[--source {research,generated,report,raw,yuxin,findera,default}]
staging_save.py: error: argument --source: invalid choice: 'quant' (choose from 'research', 'generated', 'report', 'raw', 'yuxin', 'findera', 'default')
根因:staging_save.py v1.x 的 --source 是 argparse choices 白名单,任何不在 7 个合法值内的字符串直接被 argparse 拒绝,没有 fallback。
7 个合法值(必背):
| 值 | 语义 | 典型场景 |
|---|---|---|
research |
调研(行业/竞品/学术) | 量化因子调研、AI 技术综述 |
generated |
生成(AI 输出/草稿) | AI 自动产出的初稿 |
report |
报告(已完成交付物) | 项目结项报告、合规报告 |
raw |
原始数据 | 抓取的 JSON/CSV 等中间产物 |
yuxin |
玉芬整理 | 玉芬统一的整理/归档资料 |
findera |
寻元采集 | FindEra 系统产出 |
default |
兜底 | 不推荐主动用,留作 fallback |
实战踩坑案例(2026-08-30):
5 同事协作宽博士量化因子库任务的派单文件 ~/.hermes/orchestration/messages/<agent>/inbox/task_20260830_量化因子调研.md 全部写错:
# ❌ 错误:派单原文
python3 /Users/hua/.hermes/scripts/staging_save.py \
--title "..." --content @<file>.md \
--source quant --agent heidou
# 报错:argument --source: invalid choice: 'quant'
5 个同事(黑豆/老莫/小宝/阿福/毛豆)同时收到此派单 → 5 个 inbox 都含错示例 → 全员踩坑。
修复方案(三选一):
方案 A(推荐 ✅):改派单示例 + 扩展 staging_save.py 合法 source
- 短期:玉芬把 5 份 inbox 派单文件 +
references/agent-rollout-procedure.md+templates/task-dispatch-to-agent.md里的--source quant全部改写为--source research(语义最接近) - 长期:扩展 staging_save.py
--source choices,加quant / heidou / maodou / afu / xiaobao / laomo / community(按 agent 名扩展,但要评估对 scanner 路由的影响)
方案 B(应急,任务执行时):就近 fallback + 记录偏差
# 把 --source quant 改成 --source research(语义最接近"调研")
# 加 --subdir 07-量化因子(自定义子目录做路由标识)
python3 /Users/hua/.hermes/scripts/staging_save.py \
--title "财务基本面因子与数据合规_黑豆_20260830" \
--content @<file>.md \
--source research \
--subdir 07-量化因子 \
--agent heidou
# 在 kanban task_events 评论里记录偏差:
# "派单 --source quant 实际不被 staging_save.py 支持(合法值: research/generated/report/raw/yuxin/findera/default), 已自动用 research 入站, --subdir 07-量化因子 做路由"
方案 C(根治):从 staging_save.py 源码层移除 choices 限制
# staging_save.py 现状(白名单):
parser.add_argument("--source", choices=["research","generated","report","raw","yuxin","findera","default"])
# 改为(任意字符串都接受,但保留 enum-like 注释):
parser.add_argument("--source", default="research", help="One of: research/generated/report/raw/yuxin/findera/default/<agent_name>")
但这会破坏现有 scanner 的 source 路由逻辑(scanner 按 source 子目录分类),改前必须先梳理 scanner 路由表。
关键纪律:
- 任何新派单模板/协作通知,必须先跑一次 staging_save.py --help 确认 --source 合法值
- 不要在派单文件里假设
quant/maodou/compliance/analysis等扩展值可用 - 错值导致的任务失败,务必在 task_events 评论里留 audit trail
- 派单发送前自检命令:
grep -E "source (quant|maodou|heidou|afu|xiaobao|laomo|community)" <派单文件>→ 输出空 = 安全
关联陷阱:
- 陷阱 13(workspace/knowledge 三路径分离):说的是落盘路径
- 陷阱 14(stage(agent=...) 必须是顶层 kwarg):说的是调用签名
- 陷阱 15(--source 非法值踩坑):说的是参数合法性,影响范围最广(全员派单)
⚠️ 陷阱 12: 304-公司运营/ 16 个子目录里有 4 个空白(HR/、知识产权/、财务/、销售/)
补充(2026-08-13):已新增激活目录
公司证件/,营业执照 PDF+JPG 归档于此。公司证件(执照/银行账户/收款码等)统一归304-公司运营/公司证件/,详见references/company-certificates-archive.md。
状态:4 个目录是占位空目录,等待激活;销售/ 与 销售与市场营销/ 重复。
规则:
- 新建运营资料时,先确认目标子目录已激活;未激活的写到
产品研发全链条/或B2B工业品营销/等"已激活"目录 - 不要往空白目录里写(后续清理时会被判定为"误写")
- 重复目录(
销售/vs销售与市场营销/)一律写带后缀的、已激活的那个
监控与排错
# RKR scanner 实时日志
docker logs rkr-staging-pool --tail 50 --follow
# 中转站现状(看哪些文件还没被处理)
ls -lt ~/rkr_staging/文档中转站/ | head
# 文档库现状
ls -lt ~/rkr_staging/文档库/ | head
# RKR API 健康
python3 ~/.hermes/scripts/staging_query.py stats
历史资料批量迁移(从旧位置 → 中转站)
场景:agent 以前生成过资料,散落在 ~/Desktop/渔芯科技/* 或 ~/.hermes/profiles/<agent>/home/...,需要统一搬到中转站。
用 migrate_agent_artifacts.py:
# Dry run 先看数量
python3 ~/.hermes/scripts/migrate_agent_artifacts.py --dry-run
# 全量执行
python3 ~/.hermes/scripts/migrate_agent_artifacts.py --execute
# 只迁 desktop / 只迁 profiles
python3 ~/.hermes/scripts/migrate_agent_artifacts.py --execute --only desktop
python3 ~/.hermes/scripts/migrate_agent_artifacts.py --execute --only profiles
# 测试用(小批量)
python3 ~/.hermes/scripts/migrate_agent_artifacts.py --execute --limit 100
默认扫描范围 + 排除规则(详见 references/migration-rules.md):
| 来源 | 包含 | 排除 |
|---|---|---|
~/Desktop/渔芯科技/ |
.md/.json/.pdf/.docx etc. | 00-FindEra寻元/(寻元不动) |
~/.hermes/profiles/<agent>/home/ |
同上 | Library/、node_modules/、.cache/、site-packages/、__pycache__/、.git/、dist/ |
~/Desktop/ 顶层 |
同上 | 同上 |
关键行为:
- 复制而非移动(原文件保留)
- 每个 .md 加
<!-- migration_meta -->frontmatter(含source_path/agent/migrated_at) - 每个文件配套
.meta.json(RKR scanner 友好的元数据) - 路径镜像:
<原路径相对>→migration_<日期>/<来源>/<相对路径>
已验证规模:14,879 文件 / 469 MB / 0 错误(2026-07-30 一次跑完)。
⚠️ 脚本陷阱(亲历):不要用 sorted(set(files)),那会按 ASCII 排序把 /.hermes/... (47 < 68 D) 排到 ~/Desktop/... 前面,导致 --limit N 截断错乱。正确做法:list(dict.fromkeys(files)) 保留采集顺序(desktop → profiles)。
GitHub 仓库 → 中转站 同步
场景:GitHub 上的 openclaw-cn-dev/yuxin-skills 仓库(Hermes/Claude/Codex 跨 agent 的 skills)需要 mirror 到 RKR 中转站入库。
用 sync_yuxin_skills_to_staging.sh:
# 手动同步一次
~/.hermes/scripts/sync_yuxin_skills_to_staging.sh
行为:
git pull增量到/tmp/yuxin-skills-sync-cache/rsync -a --exclude='.git'mirror 到~/rkr_staging/文档中转站/yuxin-skills-YYYYMMDD/- 健康检查:文件数 < 600 自动重 mirror(防 scanner 误清)
已验证规模:833 文件 / 10MB(claude-code 33 + hermes 230 + codex 14 + drawing-skills 8 skills)。
这个 pattern 跟
codex_self_evolution.py里"GitHub sync 到 yuxin-skills/codex/"的 cron 已注册的逻辑是相同的(每小时跑一次6dfcbdeac7bf)。
Cron 自动监控
已注册的 cron job
| job_id | schedule | 任务 | 来源 |
|---|---|---|---|
6dfcbdeac7bf |
every 60m |
Codex 配置 → yuxin-skills GitHub 同步 | codex_github_sync.sh |
955afce881f0 |
0 3 * * 0(每周日 3:00) |
Agent 历史资料 → RKR 中转站(增量) | migrate_incremental.sh |
e2052c9b44c8 |
0 9 * * 1(每周一 9:00) |
工作空间每周审计(3-公司项目资料/ 下 7 天内新增/修改) | audit_workspace.py(有变更才发,无变更静默) |
工作空间审计 cron 设计要点(e2052c9b44c8):
- 跑脚本
~/.hermes/scripts/audit_workspace.py(也作为 skill 标准资产放在scripts/audit_workspace.py) - no_agent=True(纯脚本,LLM 不介入)
- 审计范围:
~/rkr_staging/文档库/3-公司项目资料/下,排除 RKR 资源(awesome-*/cad_samples/material_library/mech_drawing 等)+ EDAI 测试 + 个人脚本目录 - 报告输出:每个 agent 写了多少文件 + 文件名清单 + 大小 + 类型分布
- 静默策略:有变更才发报告,无变更静默(no_agent 模式下空 stdout → 不发飞书)
- 用途:玉芬每周一 9:00 拿到审计报告后,扫描异常(比如某 agent 突然大量删文件)立即通知华哥
为什么需要审计:
3-公司项目资料/是工作空间(可写),没有 RKR scanner 的天然索引- 同事写文件没有强制记录,变更不可见
- 每周审计让华哥和玉芬"看见"工作空间的实际变化,异常时立即响应
增量迁移 cron 细节:
- 调
migrate_incremental.sh(wrapper bash)→ 调python3 migrate_agent_artifacts.py --incremental --execute - manifest 跟踪:
~/.hermes/state/migration_manifest.json(用mtime + size做 key) - 日志:
~/.hermes/logs/migrate_incremental_cron.log - 触发时检查 7 个 agent profile +
~/Desktop/渔芯科技/的资料类文件 - 不动寻元(
00-FindEra寻元/排除)+ 不开发项目(开发项目代码不在扫描范围内)
注册新 cron 的模板
# 注册 hourly 轻量 sync(已有 cron 可复用)
cronjob action=list # 看现有 job
# 类似 6dfcbdeac7bf / 955afce881f0 的 wrapper pattern(`script=` 传相对路径,no_agent=True)
关联
- RKR 项目根:
/Users/hua/6-产品研发/01-RKR知识库/ - RKR staging 监听:
backend/app/tasks/local_staging_scanner.py(每 60 秒扫一次,自动入库 + 删原文件) - RKR staging 配置:
backend/app/services/staging_config.py(DEFAULT_STAGING_DIR = ~/rkr_staging/文档中转站) - 现有 RKR API 集成参考:
~/.hermes/skills/research-collection/references/findera-rkr-pipeline.md - FindEra 保留 API 模式: 走
POST /api/v1/staging/upload(X-API-Key) — 不要让寻元改走 staging 文件系统
References(本目录下)
references/***SECRET***.md— v1.4.1 新增:agent personal zone 内workspace/knowledge/与 staging 中转站、scanner 归档目标的三路径分离实战教训 + 强制三路径同步 SOP(2026-08-24 实战:08-23 项目合作 v1.1 漏归档 4h)references/huage-idea-recording.md— 华哥想法记录与归档工作流(5要素结构 + staging_save.py --tag 想法 + 飞书回执三段式 + 记忆同步)references/scanner-architecture.md— RKR scanner 详细时序、配置来源、故障行为references/company-certificates-archive.md— 公司证件(营业执照等)归档位置 + 证件文件真实存放处(微信接收文件,非"素材图片") + 扫描件 pdftoppm→vision 读取技巧(2026-08-13 建立)references/migration-rules.md—migrate_agent_artifacts.py完整扫描/排除规则表references/findera-exception.md— 为什么 FindEra 不走 staging 文件系统references/hermes-profile-env-pitfall.md—$HOME被 Hermes profile 改写的陷阱 + 修复references/document-library-layout.md—~/rkr_staging/三层目录树与各子目录职责(2026-08-03 实测)references/agent-personal-zone.md— 5 个同事 agent 在301-智能体/<name>/下的 personal zone 规范references/agent-rollout-procedure.md— 5 同事 AGENTS.md 下发流程 + 已知坑 + 各 agent 业务特殊说明(2026-08-03 建立)references/***SECRET***.md— 5 个 agent 工作空间归位操作手册 v2:4 类归位决策(A 保留/B 走中转/C 清理/D 留最新)+ 各 agent 任务清单 + 严禁清单(2026-08-03 玉芬固化,基于 5 个 personal zone 扫描结果)
Templates
templates/agent-workspace-sop.md— 给 5 个同事 AGENTS.md / TOOLS.md 用的"路径 SOP"模板(可直接复制粘贴)templates/task-dispatch-to-agent.md— 5 个同事"任务派发"模板,放在3-公司项目资料/301-智能体/<agent>/根目录,让同事下次启动看到任务清单(2026-08-03 玉芬建立,基于 v2 归位任务派发)
Scripts
scripts/audit_workspace.py— 工作空间每周审计脚本:扫描3-公司项目资料/7 天内新增/修改文件,按 agent 分组,生成 markdown 报告(有变更才输出,no_agent=True 静默模式)。配套 cron job_ide2052c9b44c8(每周一 9:00)
🤖 玉芬维护 · 2026-09-13 · v2.0.0 🆕 v2.0.0: v3 时代开关 — frontmatter description 与正文顶部 v3 横幅声明 staging_save/staging_query/中转站全线废用,现行标准=直接写 ABCZ 四版块;新增
references/doclib-v3-2026-09-13.md(完整 v3 落位标准:四版块结构、旧→新路径映射、6 步采集判断流程、硬性禁区、下发落地记录含幂等推送脚本路径)。v1.5 正文降级为历史参考。 🤖 玉芬维护 · 2026-08-30 · v1.5.0 📌 适用 agent: 玉芬/毛豆/阿福/黑豆/老莫/小宝/整理师/宽博士 + 任何新 agent 🆕 v1.5.0: 新增陷阱 15 —--source非法值踩坑(派单模板示例--source quant写错导致 5 同事全员踩坑)。提升为编号 pitfall + 7 个合法值精确枚举表 + 三选一修复方案(改派单/应急 fallback/源码层移除 choices)+ 自检命令grep -E "source (quant|maodou|heidou|afu|xiaobao|laomo|community)" <派单文件>。description 加触发条件,让 agent 看到 invalid choice 错误时自动加载本 skill。 🆕 v1.4.1: 新增陷阱 13 ——agent personal zone 内 workspace/knowledge/与 staging 中转站、scanner 归档目标 是三个独立路径;staging_save 写入不等于 workspace 可见,审计脚本 grep 的 KNOW_DIR 通常是 workspace/knowledge/,必须手动 cp 兜底。实战案例:08-23 20:33 项目合作 v1.1 staging 写入但 4h 内审计脚本仍报 P0(误判),08-24 00:35 才补 cp。配套"双路径/三路径落地自检 SOP"写入进化报告模板。 🆕 v1.4.0: 微调 — 补references/agent-rollout-procedure.md(5 同事 AGENTS.md 下发流程 + 已知坑);新增 crone2052c9b44c8(工作空间每周审计);新增scripts/audit_workspace.py(审计脚本);新增templates/task-dispatch-to-agent.md(任务派发模板) 🆕 v1.3.0: 关键架构澄清 —3-公司项目资料/是可写工作空间(华哥 2026-08-03 明确,留给同事放"结果性报告"),而1-通用知识/2-专业知识/4-360行项目调研/仍是 RKR 归档层(只读,新资料走中转站让 scanner 自动入)。v1.0–v1.2 把整个文档库当作只读归档层是误读,现已修正。配套更新:核心心法段、"2 层 + 1 工作空间"架构段、错误 1 / 错误 9 重写、"用户硬性约束"改为"仅适用于归档层"、5 同事 AGENTS.md 全部按 v2 重下发、staging_save.py SOP 拆为 A(业务报告走工作空间)/B(归档资料走中转站)两类。 🆕 v1.2.0: 新增"3 层架构(写/读/个人)"心法 + pitfall 9/10/11/12 + 2 references + 1 template 📝 v1.1.0: 批量迁移 + GitHub 同步 + cron 模式 + 4 个 references 📝 v1.0.0: 初版,写/读双路径 + 8 个常见陷阱
RKR 知识库体检(103G 重复/无效审计 SOP · 2026-09-27 实战沉淀)
华哥问「知识库 X G 大小,检查数据有没有重复、是否都是有效资料」时的标准流程(约 10 次工具调用出全景报告):
- 先定总量的真实构成(
du -sh各顶层目录)——大头往往不是文档库本体而是_backups/(历史全量快照)和 pgdata 等运行数据。2026-09-27 实测:103G = _backups 61G(两份同日快照互为重复+与主库重复)+ 文档库 31G + pgdata 7G + 其余 4G。报体积必须先拆构成,否则清理方案全错。 - 重复检测分层跑:
- 系统性副本目录:
find -type d -name "*dup*"——*_dup1类目录是采集管道的已知重复产物(实测 5.5G/4330 文件,抽样 MD5 验证 ≥100MB 的 glb 双份仅文件名不同) - 散点同内容:只对 >1MB 文件跑 MD5(先按体积分组、同体积才可能同内容、组内逐个 hash),控制耗时在 5 分钟内。实测 1439 个 >1MB 文件中 119 组重复、可省 2.46G
- 仓库嵌套:
find -type d -name ".git"统计体积(知识库里的 GitHub mirror 应去 .git 浅存;实测 8 个共 283M;antigravity-awesome-skills 同一套 skills 存 3 份共 447M)
- 系统性副本目录:
- 无效资料特征扫描:0 字节文件(247 个)/ .DS_Store(154)/ pycache / .pytest_cache / 乱码内容抽样(head 看是否二进制乱码——Z4-低质抓取碎片 1.7G/10.8 万文件实锤全是乱码)/ 废用路径残留壳(对照 AGENTS.md 的禁区与废用清单:
3-公司项目资料/、通用知识库/、cleaned/、渔芯项目/等 v1.x 旧结构) - 报告格式(华哥偏好):构成表 → 重复问题按严重度 P1/P2/P3 → 无效资料表 → 有效资产盘点(明确哪些必须保留,如手语数据集 15G 是立项产品正本)→ 分步清理方案表(每步标回收量+风险等级)→ 流程问题单列(比磁盘更紧急的,如"已废用的中转站今天仍有写入")。报告落盘到
文档库/_audit/。 - 清理执行纪律:快照删除不可逆,必须等华哥拍板再动手;dup 目录删除前先全量 hash 复核;给方案时区分"最小方案"(只删快照,回收 61G)和"完整方案"(全部清理,回收 68-70G)两档供选择。
2026-11-02 增量:入库前资料审查(MD5 全量去重 + 中间产物剔除)
华哥问「先审查准备上传的资料是否有效、有没有重复」时,直接跑 scripts/rkr_material_audit.py(自包含可复用,支持传 ROOT 参数)。2026-11-02 实测 ~/rkr_staging 48G / 66.1 万文件:
- 文档类 32.2 万,MD5 完全重复 91,328 副本 / 49,359 组(28.3%,浪费 747MB),最大单组 68 份 —— 重灾区
Z-共享/Z1-通用学科知识、Z4-低质抓取碎片(采集系统反复抓同一文章,文件名哈希_日期_哈希.md) - 中间产物约 30GB 不该入库:mp4 13.3GB(采集视频)/ npy 1.37GB(向量缓存)/ zst 5.28GB(
_archive已废弃管道)/ glb*_dup13.93GB / zip / 图片 / postgres·redis 数据库文件
三个新 pitfall(2026-11-02 实测踩坑):
- tab 文件名坑:写
size\tpath中间清单再回读,路径含 tab →partition("\t")错位报ValueError: invalid literal for int() with base 10。必须 os.walk 现场 getsize,别生成中间清单(脚本已按此实现)。 - postgres/redis 数据库文件被误判空文档:
find -size 0会扫到zhinangtuan/postgres/global/*、PG_VERSION等 0 字节库文件。SKIP_DIRS 必须含postgres/pg_logical(不只pgdata)。排除后真·空文档仅 ~128 个(FreeCAD 库自带空 README),有效性基本过关。 - 重复信号目录/命名清单(比逐文件 MD5 更快的第一轮定位):
*_dup1目录、_archive_YYYYMMDD/归档、采集碎片哈希_日期_哈希.md、多版本日期戳文件名(框架式滚筒过滤器2_20260731_*.glbvs4-框架式滚筒过滤器2_20260730_*.glb)。先find -type d -name "*dup*"秒级暴露,再对文档类做 MD5 精确定量。
报告让华哥拍板(危险动作不擅自动手,删除/清理前必等批准):a) 只去重(每组保留 1 份)b) 去重 + 中间产物目录从入库范围排除(不删文件,只标排除)c) 只要报告暂不动手。
2026-11-03 增量:华哥定调「反过度开发 / 重头来」+ 源头梳理极简闭环
方向转折(此后 RKR 工作的唯一正确方向):华哥明确 RKR 之前「本地能跑」一路加码到 6 容器+知识图谱+云端双管道是过度开发,要「重头来一次、从源头开始、整体闭环」。不要再在现有重架构上堆功能,走极简闭环:干净文档 → 单容器 PG+pgvector → 单一 embedding → 语义检索+RAG,砍掉图谱/实体/ES/MinIO/Celery/10步管道/双模型,容器 6→2。
源头梳理实锤:~/rkr_staging/文档库 31G 里 30.9万 md/txt → 8万真家底(61% 是垃圾:Z3 管道产物 8万=第三方 license/代码库文件、Z4 低质碎片 10.8万=多语言乱码网页;A/B 类去重率 37-38%)。完整诊断数据、垃圾识别特征、三阶段方案、待拍板点、脚本位置见 references/rkr-source-reset-2026-11-03.md。
RKR 文档库盘点与重组档案(curator 合并 · 原 rkr-doclib-inventory)
RKR 文档库盘点与重组档案(curator 合并 · 原 rkr-doclib-inventory)
三大版块结构事实(渔芯科技/渔芯社区/渔芯独角兽)、盘点方法论、62 万文件物理搬迁执行 SOP(2026-09-12 已完成零丢失)、文档库 INDEX 重建 SOP、清理分级审计。一次性搬迁已收口;再次盘点/迁移/清垃圾时读 references/rkr-doclib-inventory.md(执行日志与审计清单同在 references/rkr-doclib-*.md)。