| name | life-index |
| description | Personal life journaling system with dual-dimension indexing. Use when user says 'record journal', 'log this', 'search logs', 'generate summary', '记日志', '写日记', '搜索记录', '生成摘要'. Features: auto weather, semantic search, attachment handling. |
| user-invocable | true |
| disable-model-invocation | false |
| metadata | {"clawdbot":{"emoji":"📖","requires":{"bins":["python"]}}} |
| triggers | ["/life-index","记日志","写日记","记录一下","write journal","daily log","log this","record this"] |
Life Index Agent Skill
Authority Chain: bootstrap-manifest.json 是 freshness / authority anchor。涉及安装、升级、repair、环境判断时,必须先刷新 bootstrap-manifest.json,再按其 required_authority_docs 刷新对应文档,然后才允许 sync checkout 或 route 判断。
工具参数与错误码: 详见 API.md
Triggers & When to Use
| 意图 | 触发词 | 工具 |
|---|
| 记录日志 | "记日志"、"记录一下"、"写日记"、"记下来"、"log this"、"record this"、"write journal" | write_journal |
| 搜索日志 | "查找日志"、"搜索记录"、"找一下关于...的日记"、"search journal"、"find log" | search_journals |
| 智能搜索 | "帮我回忆..."、"我和女儿之间有哪些珍贵的回忆?"、"smart search" | smart_search |
| 编辑日志 | "修改日志"、"补充日记"、"更新记录"、"edit journal"、"update log" | edit_journal |
| 实体图谱 | "列出实体"、"解析人物关系"、"entity graph"、"谁是谁的..." | entity |
| 生成摘要 | "生成摘要"、"月度总结"、"年度总结"、"generate summary" | generate_abstract |
| 修订历史 | "查看修订历史"、"编辑记录" | edit_journal |
| 定时报告 | 日报/周报/月报/年报 | 参考 SCHEDULE.md |
Quick CLI Reference
⚠️ 所有命令须在技能根目录(本文件所在目录)下执行。所有 Python/CLI 命令必须通过虚拟环境调用。
跨平台 venv 路径规则:
- Linux/macOS/WSL:
.venv/bin/life-index 或 .venv/bin/python
- Windows:
.venv\Scripts\life-index 或 .venv\Scripts\python(首次排障/验证时优先显式使用此路径)
.venv/bin/life-index write --data '{"title":"...","content":"...","date":"2026-03-14","topic":["work"],"abstract":"...","mood":[],"people":[],"project":"","tags":[],"links":[]}'
.venv/bin/life-index search --query "关键词" --topic work --level 3
.venv/bin/life-index search --query "学习"
.venv/bin/life-index smart-search --query "我和女儿之间有哪些珍贵的回忆?"
.venv/bin/life-index smart-search --query "..." --no-llm
.venv/bin/life-index smart-search --query "..." --explain
.venv/bin/life-index edit --journal "Journals/2026/03/life-index_2026-03-14_001.md" --set-location "Beijing"
.venv/bin/life-index entity --list
.venv/bin/life-index entity --resolve "乐乐的奶奶"
.venv/bin/life-index abstract --month 2026-03
.venv/bin/life-index weather --location "Lagos,Nigeria"
.venv/bin/life-index index
.venv/bin/life-index index --rebuild
.venv/bin/life-index health
.venv\Scripts\life-index write --data @first-entry.json
.venv/bin/python -m tools.write_journal --data '{...}'
.venv/bin/python -m tools.search_journals --query "关键词"
.venv/bin/python -m tools.edit_journal --journal "..."
.venv/bin/python -m tools.generate_abstract --month 2026-03
.venv/bin/python -m tools.query_weather --location "Lagos,Nigeria"
.venv/bin/python -m tools.build_index
安装 / 首次验证 / 故障恢复指针:
- 首次安装、upgrade、repair、fresh install 判断 → 读
AGENT_ONBOARDING.md
ModuleNotFoundError、venv 损坏、health 异常、Windows 首次写入转义问题 → 先读 AGENT_ONBOARDING.md
- 写入成功后的状态字段解释(
needs_confirmation / index_status / side_effects_status / 附件处理计数)→ 读 docs/API.md 中 write_journal 返回语义
Project Structure
life-index/ # 技能根目录
├── SKILL.md # [本文件] 技能定义
├── tools/ # 可执行工具目录
│ ├── write_journal/ # 写入日志(天气查询、附件处理、索引更新)
│ ├── search_journals/ # 搜索日志(L1/L2/L3 + 语义搜索)
│ ├── smart_search/ # LLM 编排智能搜索
│ ├── edit_journal/ # 编辑日志(修改元数据、追加内容)
│ ├── entity/ # 实体图谱(list/add/resolve/update)
│ ├── generate_index/ # 生成索引树(monthly/yearly/root)
│ ├── build_index/ # 构建索引(FTS5 + 向量索引)
│ ├── query_weather/ # 查询天气
│ ├── backup/ # 备份日志数据
│ ├── verify/ # 数据完整性校验
│ ├── timeline/ # 时序摘要流
│ ├── migrate/ # Schema 链式迁移
│ ├── eval/ # 搜索质量评估
│ ├── dev/ # 开发/验收辅助工具
│ └── lib/ # 共享库(SSOT)
├── docs/ # API.md, ARCHITECTURE.md
└── references/ # WEATHER_FLOW.md, SCHEDULE.md
关键约定:
- 虚拟环境: 所有命令通过
.venv/bin/(Windows: .venv\Scripts\)前缀调用
- 用户数据目录:
~/Documents/Life-Index/(日志、附件、索引,与代码物理隔离)
- 跨平台路径: 自动处理(Agent 传原始路径即可,工具自动转换 Windows↔WSL)
- 健康检查: 遇到异常时先运行
.venv/bin/life-index health 诊断
Core Constraints
Content Preservation (MUST)
100% 保留用户原始输入:
- 不修改段落结构
- 不改变标题层级
- 不转换列表格式
- 不添加序号标记
- ⚠️ 不修改文件名(不在中英文间添加空格)
# ❌ 错误
用户输入:"1、完成A 2、完成B"
Agent 改成:"1. 完成A\n2. 完成B"
# ❌ 错误(文件名被修改)
用户附件:"C:\Users\test\Opus审计报告.txt"
Agent 改成:"C:\Users\test\Opus 审计报告.txt" ← 添加了空格
# ✅ 正确
用户输入什么,content 和附件路径就原封不动传递什么
Guardrails
- 永不删除文件:编辑只修改内容
- 数据隔离:数据在
~/Documents/Life-Index/,与代码分离
- 天气处理:详见 WEATHER_FLOW.md
❌ 不要:假设用户知道内部概念(如"by-topic索引")
✅ 必须:用人话说明(如"已归类到工作相关")
❌ 不要:一次问多个问题
✅ 必须:"地点和天气是否正确?"(单次确认)
天气与地点确认(强制)
⚠️ 最常见错误点:看到 success: true 就直接结束对话
调用 write_journal 后,检查返回的 needs_confirmation 字段:
{
"success": true,
"journal_path": "...",
"needs_confirmation": true,
"confirmation_message": "地点:Lagos, Nigeria;天气:晴天 33°C"
}
❌ 错误:工具返回 success: true → Agent 直接结束:"日志已保存"
✅ 正确:工具返回 needs_confirmation: true
→ Agent:日志已保存。地点:Lagos, Nigeria;天气:晴天 33°C。是否正确?
→ 等待用户回复
⚠️ 用户纠正地点时的完整流程(Correction Flow):
当用户说"地点不对,应该是 XXX"时,必须修改已保存的日志,不能重新调用 write_journal 创建新日志。
❌ 错误:用户纠正地点 → Agent 重新调用 write_journal → 创建了第二篇日志
✅ 正确:用户纠正地点
→ Agent 查询新地点天气(query_weather --location "XXX")
→ Agent 调用 write_journal confirm --journal "<journal_path>" --location "XXX" --weather "新天气"
或调用 edit_journal --journal "<journal_path>" --set-location "XXX" --set-weather "新天气"
→ 日志原地更新,不产生新文件
Required Metadata Fields
写入日志时,必须包含所有元数据字段(即使为空值):
| 字段 | 类型 | 必填 | 说明 |
|---|
| title | string | ✅ | 日志标题 |
| content | string | ✅ | 日志正文(100%原样保留) |
| date | string | ✅ | ISO 8601 日期时间 |
| abstract | string | ✅ | ≤100字摘要(Agent生成) |
| topic | array | ✅ | 主题分类(见下方 Topic 表) |
| mood | array | ✅ | 心情标签,Agent语义提取1~3个(如["开心","专注"]) |
| tags | array | ✅ | 标签,Agent语义提取关键词(可多个) |
| location | string | ❌ | 地点;用户未指定时默认 "Chongqing, China",写入后必须走地点/天气确认 |
| weather | string | ❌ | 天气,根据确认的地点自动查询 |
| people | array | ❌ | 相关人物,Agent语义提取,没有则留空 |
| project | string | ❌ | 关联项目,Agent语义提取,没有则留空 |
| links | array | ❌ | 相关链接 |
| attachments | array | ❌ | 附件(自动检测 content 中的本地文件路径;也可显式传递 {"source_path":"...","description":"..."} 对象) |
| entities | array | ❌ | 已匹配的 entity graph ID 列表 |
写入增强(已实现)
- 写入结果现在可包含:
entities
- 编辑日志时会自动写入 co-located
.revisions/
Tool Schema(已实现)
- 每个 CLI 工具目录下均已提供
schema.json
- Agent Runtime 可读取 schema 发现参数/返回值契约
- 高频意图:"列出工具"、"工具参数"、"schema"
Entity Graph(已实现)
- CLI:
life-index entity --list|--add|--resolve|--update
- 存储:
~/Documents/Life-Index/entity_graph.yaml
- 操作规范:见
docs/ENTITY_GRAPH.md
- 作用:
- 搜索时做 alias / relationship query expansion
- 写入时标记
new_entities_detected
- 当前最小支持类型:
person / place / project / event / concept
Topic 分类(必填)
SSOT:tools/lib/llm_extract.py VALID_TOPICS(含验证逻辑,无效值静默丢弃)。下表为 Agent 便捷参考,若与代码不一致以代码为准。
| Topic | 含义 | 示例场景 |
|---|
work | 工作/职业 | 项目进展、会议、职业发展 |
learn | 学习/成长 | 读书笔记、课程学习、技能提升 |
health | 健康/身体 | 运动、饮食、体检、医疗 |
relation | 关系/社交 | 家人、朋友、社交活动 |
think | 思考/反思 | 人生感悟、决策思考、复盘 |
create | 创作/产出 | 文章、代码、设计作品 |
life | 生活/日常 | 日常琐事、娱乐、购物 |
Agent 职责
- 必填字段:title, content, date, abstract, topic, mood, tags — 必须有值
- 语义提取:从用户内容中主动提取 mood(1~3个)、tags(关键词)、people、project
- 地点规则:正文里明确写出的地点优先;只有正文和入参都未提供地点时,工具才使用默认地点;但无论地点来源为何,只要写入成功,Agent 都必须展示确认信息并等待用户确认或修正
- 空值处理:people, project, links 未提取到时传空值(如
"people": [])
- 摘要生成:从 content 提取关键信息,生成 ≤100 字的 abstract
- 必须确认:工具返回后检查
needs_confirmation;对所有成功写入结果,这都应视为必须执行的 follow-up
Workflows
意图澄清(强制)
当用户请求可能被解读为多种操作时,必须先澄清再调用工具:
| 歧义类型 | 示例 | 正确处理 |
|---|
| 写入 vs 编辑 | "把今天晚饭记进去,或者如果有了就补进去" | 先询问:是新建日志还是修改已有日志? |
| 编辑目标不明确 | "把那篇写深圳的日志改一下" | 先搜索确认目标,再执行编辑 |
| 修改范围不清 | "更新一下昨天的日志" | 先确认要修改哪些字段 |
❌ 错误:猜测用户意图,直接调用工具
✅ 正确:明确意图后再调用工具
工作流1: 记录日志
| 步骤 | 动作 | 关键检查点 | 常见错误 |
|---|
| 1 | 解析意图 | 提取 title, content, date, topic | 遗漏 topic |
| 2 | 提取元数据 | 识别 mood(1-3个)、tags、people、project | mood 为空数组 |
| 3 | 生成摘要 | abstract ≤100字 | 摘要过长 |
| 4 | 调用工具 | write_journal 包含所有字段;正文里明确地点/天气时优先采用正文信息;location 缺失时才允许工具使用默认地点 | 让默认值覆盖正文里已写明的信息 |
| 5 | 检查确认 | needs_confirmation 为 true?(成功写入后必须 follow-up) | ⚠️ 最常见错误:直接跳过 |
| 6 | 展示确认 | 展示 confirmation_message | 不展示直接结束 |
| 7 | 等待回复 | 询问用户"是否正确?" | 不询问 |
澄清规则(强制):
- 如果无法判断用户是在“新写一篇”还是“修改已有日志”,必须先澄清
- 如果无法负责任地构造最小可写 payload,必须先澄清再调用
write_journal
- 不得把缺失的用户意图留给工具在运行时“猜出来”
失败与后续规则(强制):
- pre-tool 阶段若意图或关键字段不清楚,先澄清,不得直接调用工具
- tool failure 时,不得假装 journal 已保存
- write succeeded 但用户拒绝自动补全值时,应进入 correction flow,不得把已成功写入重新表述为“写入失败”
- 必须区分:未保存 / 已保存但待确认 / 已保存但存在降级 side effects
安装后可选个性化与写入状态指针:
- 安装完成后的专用触发词 / 默认地址偏好配置 → 读
AGENT_ONBOARDING.md 的 optional customization step
- 场景:想调整 trigger、设置默认地址、区分“已保存”与“已验证生效” → 先读
AGENT_ONBOARDING.md
- 场景:需要解释
write_journal 的 needs_confirmation / index_status / side_effects_status / 附件处理结果 → 先读 docs/API.md 的 write_journal 返回语义
SKILL.md 保留 workflow 与职责边界;安装细节和返回字段契约不在此重复展开
工作流2: 检索日志
检索架构:
检索管道与编排器架构的完整细节见 ARCHITECTURE.md §5。
以下为简化概览:
用户查询
┌────┴────┐
┌──────▼──────┐ ┌──────▼──────┐
│ Pipeline A │ │ Pipeline B │
│ 关键词管道 │ │ 语义管道 │
└──────┬──────┘ └──────┬──────┘
└────┬────┘
RRF 融合排序 (k=60)
│
最终结果
对于复杂自然语言查询,smart-search 在双管道之上增加 LLM 编排层(改写→检索→精筛),详见 ARCHITECTURE.md §5.8。
查询意图 → 参数映射:
| 用户意图 | 推荐参数 |
|---|
| "关于工作的日志" | --topic work |
| "去年的记录" | --date-from 2025-01-01 --date-to 2025-12-31 |
| "跟乐乐有关的" | --people 乐乐 |
| "关于重构的" | --query "重构" |
| "开心的回忆" | --mood 开心 |
| "LifeIndex项目" | --project LifeIndex |
| 精确关键词匹配 | --query "关键词" --no-semantic |
步骤:
- 解析查询意图:从用户表述中识别过滤条件
- 执行搜索:
search_journals(双管道自动启用)
- 呈现结果:展示日志列表(按 RRF 分数排序)
职责边界(强制):
search_journals 负责 retrieval execution,不负责替用户下结论
- Agent 必须区分“搜索结果为空”与“搜索执行失败”
- Agent 负责解释结果、回答用户真正的问题,并在需要时建议 refinement / follow-up
- 不得把工具返回的原始结果列表直接等同于最终用户答案
澄清与失败规则(强制):
- 当用户请求过于模糊、无法形成有意义的 query / filter 时,应先澄清,再调用
search_journals
- 如果工具执行失败,不得把 failure 伪装成“没搜到”
- 如果工具成功但无结果,应如实说明为空结果,并可建议用户缩小/放宽条件
- 如果用户在搜索后其实想继续执行 edit / summarize / compare,Agent 必须显式切换到下一工作流,而不是默认混做
工作流2.5: 聚合型自然语言查询
适用场景:
- “过去30天我有多少次晚于10点睡觉”
- “上个月我写了多少篇关于工作的日志”
- “最近两周我情绪低落的次数多吗”
- “去年这个时候我主要在做什么”
核心原则:
- 聚合型问题不是单次 retrieval 的直接结果,而是 检索 → 阅读证据 → 条件判定 → 聚合回答
- 不得把
search_journals.total_found 直接当作最终答案,除非用户问的就是“搜到了几条”
- 优先使用确定性证据;启发式证据只能辅助判断,不能伪装成硬事实
步骤:
- 识别问题类型:判断用户要的是 count / compare / trend / summarize
- 提取时间窗与过滤条件:优先形成
date-from/date-to/topic/project/people/...
- 优先找硬证据:
- frontmatter 明确字段
- 正文明确陈述
- index / timeline / metadata 可直接回答的信息
- 必要时做候选检索:调用
search_journals,必要时围绕同一用户问题做多轮 query expansion
- 逐条判定证据:
MATCH:明确满足
NO_MATCH:明确不满足
UNCERTAIN:存在相关线索,但证据不足
- 聚合输出:count / compare / trend / summary,并明确区分确定结论与启发式推断
证据分层(强制):
- 硬证据:结构化字段或正文明确陈述
- 软证据:只能间接支持结论的 proxy signal(如日志写作时间很晚、正文出现“熬夜/很困/准备睡”)
- 不确定证据:不足以单独支撑结论,只能作为补充说明
启发式规则(强制):
- Agent 可以使用软证据做推断,但必须降级表达为“高概率 / 可能 / 无法确认”
- 不得把启发式结论写成 CLI 硬规则
- 不得为某个具体问题发明专门 workflow 分支;应复用本工作流的证据分层与聚合步骤
职责边界(强制):
- CLI 负责提供原始证据与检索结果
- Agent 负责条件判定、聚合、解释不确定性
- 如果结论高度依赖启发式,必须在最终回答中说明依据与局限
工作流3: 编辑日志
- 定位日志:根据日期或标题找到目标文件
- 确认修改:展示当前内容,明确修改范围
- 执行编辑:
edit_journal
- 如修改地点:必须同时更新 location 和 weather;先调用
query_weather 获取新天气,若失败可由 Agent 手动联网查询天气后再一起更新
澄清规则(强制):
- 如果目标日志不明确,必须先定位并确认,不能猜测编辑目标
- 如果不清楚用户要 append、replace 还是 metadata update,必须先澄清
- 如果请求听起来更像“新增一段人生记录”而不是“修改已有日志”,必须切回 write vs edit 澄清
确认与失败规则(强制):
- edit flow 默认不要求像 write flow 那样的 post-write confirmation loop,但对高风险 replace / destructive edit,Agent 可先做额外确认
- 如果 coupled-field prerequisite(如新地点对应天气)尚未解决,不得直接把 edit 当作可安全执行
- 如果 edit tool 执行失败,不得宣称修改已成功
- 如果 journal mutation 已完成但 weather alignment 未完成,必须诚实区分“编辑状态”和“字段语义对齐状态”
工作流4: 生成摘要
- 确定类型:月度摘要(
--month YYYY-MM)或年度摘要(--year YYYY)
- 执行生成:
generate_abstract
- 返回结果:告知文件路径和统计信息
工作流5: 索引维护
| 场景 | 操作 |
|---|
| 日常写入 | 无需手动维护(Write-Through 自动更新) |
| 搜索结果异常/缺失 | .venv/bin/life-index index --rebuild 全量重建 |
| 首次安装 | .venv/bin/life-index index 初始化索引 |
| 手动编辑过日志文件 | .venv/bin/life-index index 增量更新 |
工作流6: Schema 迁移
- 扫描:
life-index migrate --dry-run 查看版本分布和缺失字段
- 执行:
life-index migrate --apply 自动迁移 + 获取 needs_agent 列表
- 语义回填:Agent 逐条处理
needs_agent(读取正文 → LLM 提取 abstract/mood → life-index edit 更新)
工作流7: Entity 审计
- 检测:
life-index entity --audit 获取质量报告
- 访谈:Agent 逐项询问用户(合并?归档?添加别名?添加关系?)
- 执行:Agent 调用
life-index entity --update 应用用户决策
响应中的 events 和 _trace
- events:CLI 响应中的
events 字段包含搭便车事件通知(如"连续7天未记日志")。Agent 自主决定是否向用户提及。
- _trace:CLI 响应中的
_trace 字段包含操作级诊断数据(trace_id、耗时、步骤状态)。用于调试性能问题。
Related Documentation
Examples
记录工作日志:
用户:记录一下今天完成了搜索功能优化
Agent:
1. 解析:title="搜索功能优化", topic=["work"], abstract="完成搜索功能优化工作"
2. 提取:mood=["专注"], tags=["搜索", "优化"], people=[], project=""
3. 调用 write_journal(自动填充地点="Chongqing, China"、查询天气)
4. 检查 needs_confirmation=true
5. 展示:日志已保存。地点:Chongqing, China;天气:Sunny。是否正确?
搜索历史:
用户:查找去年关于重构的日志
Agent:
调用:search_journals --query "重构" --date-from 2025-01-01 --date-to 2025-12-31
返回:找到 5 篇相关日志