Skip to content

TUTORIAL.md

Latest commit

 

History

History
114 lines (93 loc) · 7.72 KB

TUTORIAL.md

File metadata and controls

114 lines (93 loc) · 7.72 KB
Raw

byteworker 上手引导(tutorial)

给 AI 助手:用户首次使用 byteworker、且同意走引导时,你读本文件,按下面的 剧本对话式地带用户走完。读一次、记住剧本即可,引导途中不要反复重新加载本文件。 用户随时说「跳过 / 不用了 / 直接开始」→ 立刻结束引导、转入正常使用 (第 1 步的建库若还没完成,仍需完成 —— 否则知识库无处可存)。

引导目标:用 2-4 分钟完成 byteworker 的核心闭环和自动化设置 —— 建知识库 → 个性化 → 摄取一篇文档 → 查询一次 → 设置自动报告。全程友好、简短, 一次只推进一步、等用户回应再继续;别堆术语。

剧本

开场(一段话)

告诉用户:byteworker 把你日常的飞书文档 / 会议 / 群聊消化成一个 可对话查询的知识库;这个引导会带你亲手做三件事 —— 建库、摄取一篇文档、查询一次 —— 大约 2-4 分钟。随时说「跳过」可跳过摄取 / 查询演示，但仍需完成知识库路径和最小个人设置。 下面保留的子命令用类似 /byteworker [子命令] [参数] 的方式使用。

第 1 步 · 创建你的知识库

  1. 解释(两句):知识库数据存在一个你指定的独立目录里 —— 不在 skill 仓库内, 含机密、绝不外传;它本身也是个本地 git 仓库,每步操作可回滚。
  2. 问用户:把知识库数据目录放在哪个父目录下?(目录名默认 byteworker_kb,可改)
  3. 按 DESIGN.md §1.B 初始化该目录,把绝对路径写进 skill 的 .kbconfig。
  4. 告诉用户:知识库建好了,在 <路径>;以后所有笔记都沉淀在这里。

第 2 步 · 个性化设置

  1. 解释（一句）：「上下文(context)」= agent 在摄取、查询、报告等语义任务中读取的格式化个人 工作信息与做事偏好；纯帮助或维护操作不必重复加载全文。
  2. 按 templates/context.md 引导用户一次性补充：
    • 自己的姓名、常用称呼 / 别名、飞书 feishu_id、时区
    • 工作所在部门、工作范围，自己管理的团队，项目范围与明确排除范围
    • 自己的主要领导、下属是谁，提取信息的时候额外关注这些人
    • 默认提醒时间、默认截止时间等交互偏好
    • 其他不在输入文档中、但需要模型知道的信息
  3. 展示最终的context内容

第 3 步 · 摄取第一篇文档

  1. 解释(两句):「摄取(digest)」= 把一份资料消化成结构化笔记 —— 不只是存档, 是抽取里面的决策、结论、人物、项目,沉淀成相互链接的节点。
  2. 要一份输入:
    • 用户在首条消息里已经给了飞书文档 / 妙记 URL 或本地 md → 直接用它。
    • 否则请用户给一个飞书文档 / 妙记 URL,或一个本地 .md 文件路径。
    • 用户手头没有、或飞书还没配好 → 不要卡住:告诉他可以稍后再摄取,本步先跳过, 直接进第 4 步、用概念讲解代替演示。
  3. 按标准 digest 流程摄取。完成后用大白话汇报:这篇资料消化出了哪些节点 (例如「3 个人物、1 个项目、2 个决策、1 个事件」)、存到了哪、原文已逐字留底。
  4. 点一句关键理念:同一个项目以后在别的文档 / 会议里再被提到,会汇聚到同一个节点 持续生长 —— 这就是「实体图」,而不是一堆散落的文件。

第 4 步 · 查询知识库

  1. 解释(一句):「查询(search)」= 用一句话问知识库,每条事实都带论文式引用 (原始文档 / 妙记录屏、原文时间、byteworker 收录时间)和置信度。
  2. 引导用户问一个问题:
    • 基于刚摄取的内容,给用户 1-2 个示例问题挑(如「关于〈某人〉我知道什么」 「我们关于〈某主题〉定过什么」),也可让他自己问。
    • 若第 2 步跳过了摄取 → 讲清楚查询会怎么工作即可,不强行演示。
  3. 按标准 search 流程查询,展示:答案中的 [S1] → 引用(原始出处 + 原文时间 / 覆盖 + 收录时间)→ 置信度。点明出处可回原文核对,收录时间用于判断是否可能过期。

第 5 步 · Todo、定期摄取、IM 摘要和自动日报/周报

  1. 用一句话示范自然语言 Todo：“明天下午三点提醒我提交周报”;说明内部编号不需要用户记, 每次 byteworker 运行会检查提醒,但无对话时不会后台推送。
  2. 解释skill的定期摄取逻辑，可以处理持续性群聊讨论、周报、日报等飞书内容的处理逻辑。
  3. 如果团队是定期周会，视频会议录屏+周报文档的模式，最佳实践是可以把周会加入定期摄取
  4. 解释日报 / 周报不再要求用户记命令，而由 Codex / Claude / TRAE 等宿主的原生本地定时任务 自动运行。每次自动日报先检查并 digest 全部已登记的定期来源，再按 context.md 中的 重点人物、重点项目和主管方向生成报告；自动周报也先 digest。
  5. 读取 references/report-scheduling.md，询问用户是否现在创建任务：
    • 默认工作日 20:30 生成当天日报，周一 09:30 生成上一完整 ISO 周周报；另用周期性补偿任务 检查离线或休眠导致的缺口；按 context 时区解释。
    • 允许修改运行日、时间和通知偏好。
    • 只能选知识库目录的本地环境，不用云端或 worktree。
    • 同意后完成授权预检、任务查重、创建与 Run now；真实验证后记录 configured。
    • 拒绝 / 稍后分别记录决定，之后不反复打扰；以后说“设置自动报告”可重开。
  6. 解释 IM Inbox Summary 的使用边界:
    • 可以用 /byteworker inbox 直接触发;例如 /byteworker inbox 扫今天, /byteworker inbox 昨天 扫上一自然日,/byteworker inbox 2026-06-01 扫指定日期。
    • 它适合用户明确说「分析昨天 / 今天飞书 IM 里的重要消息」「最近一天聊天里有什么要关注」 或「日报包含 IM」时使用;普通自动日报 / 周报默认不扫描全量 IM。
    • 它会先用 context.md 里的重点项目、人物、组织、群名、指标和风险词做本地筛选与降噪, 再只把高信号候选交给模型精判;不会把全量聊天原文默认归档进知识库。
    • 第一次运行前,要用一句话提醒用户补充关注关键词;因为命令较重,建议一天运行一次, 短时间重复运行通常收益不大。
    • 最终摘要会保存到知识库数据目录的 reports/im/<YYYY-MM-DD>.md,用于回看和给日报引用。

收尾 · 串起整个流程

  1. 三句话总结闭环:摄取(digest)把资料消化进库 → 知识沉淀成实体图持续生长 → 随时查询(search)一句话问出来、带出处。
  2. 列一下还能做什么:update 更新某条知识 · brief 会前简报 · dashboard 工作看板 · todo 自然语言待办 · 自动日报/周报 · inbox IM摘要 · help 帮助;还能在 skill 目录运行 bin/browse.sh 在浏览器里可视化浏览整个知识库。
  3. 告诉用户:引导结束,可以正常用了 —— 直接发飞书 URL 或用自然语言即可。 想再看一遍引导,说「跑一下上手引导」。

注意事项(给 AI 助手)

  • 全程对话式、简短、友好;一次只做一步,等用户回应再继续。
  • 用户随时说「跳过 / 不用了」→ 立即结束引导、转正常使用;第 1 步的建库若没完成, 仍需完成。
  • 引导途中不要反复 Read 本文件 —— 开头读一次即可。
  • 第 3 步摄取走标准 digest 扇出与「写入规范」,第 4 步查询走标准 search 流程 —— 引导只是「带着用户做一遍」,底层行为与平时完全一致,细节见 SKILL.md。