user-thoughts

name	user-thoughts
description	Persist user decisions and project constraints to mdbase across sessions. Trigger on /user-thoughts or /ustht, or when user discusses architecture, tech stack, rules, UI/UX, or mentions '想法', '记录', 'mdbase'.
license	MIT
source	JularDepick/user-thoughts.SKILL
risk	safe
allowed-tools	read write bash
metadata	{"author":"JularDepick","source_repo":"JularDepick/user-thoughts.SKILL","category":"productivity","date_added":"2026-05-31","tags":"[userthoughts, documentation, project-management, mdbase]","supported_agents":"[claude, cursor, gemini]"}

user-thoughts.SKILL

概述

跨会话、跨 Agent 时，用户积累的决策和约束会彻底丢失。user-thoughts.SKILL 将这些想法持久化到 mdbase，绑定于项目而非会话——任何接手的 Agent 读取 mdbase 即可继承用户的完整意图，无需重新推导。

重要声明

• 本 SKILL 系指本文档及同目录下内容，整体称 user-thoughts.SKILL
• 用户：使用、调用、提及本 SKILL 的发言人
• 行为边界：SKILL 只做想法分析和记录，不干预 Agent 对用户指令的执行。这是核心设计——当用户说"把按钮改成红色"时，Agent 应同时执行修改并记录偏好，两者并行互不干扰。记录行为不应延迟或阻塞用户的实际工作

When to Use

• 用户输入 /user-thoughts 或 /ustht 命令时
• 用户讨论架构、技术栈、规则、UI/UX 等项目决策时
• 用户发言中提及"想法"、"记录"、"mdbase"等关键词时
• 用户表达项目相关的需求、偏好、约束时

使用指南

• 用户发言包含项目想法、决策、需求、规则、偏好时，SKILL 自动激活
• 命令以 /user-thoughts 或 /ustht 引导（详见 references/commands.md）
• 自然语言触发兼容任何语言——Agent 应匹配用户意图，而非特定关键词

命令前缀：/user-thoughts 为完整前缀，/ustht 为简写，两者等价可互换。

激活边界：当用户发言同时包含指令和想法时（如"把这个按钮改成红色"），Agent 应执行指令并同时记录想法。仅当发言纯粹是闲聊或与项目完全无关时（如"今天天气不错"）才不激活。

语言策略

• SKILL 本体（SKILL.md、references/、assets/）语言固定为中文，不随用户语言变化
• Agent 输出适配用户语言：命令反馈、sortin 摘要、mdbase 展示、提示信息等面向用户的输出，应使用用户当前对话所用的语言——用户无需切换语言即可理解反馈
• 想法原文保留：raw 记录和 mdbase 中的想法内容保持用户原始语言，不翻译、不转换——保持原文可避免翻译引入的歧义，且用户原始表述是最权威的意图表达

工作原理

工作流

用户发言 → Agent 识别项目想法 → 写入 raw/（即时计划）
         ↓
用户执行 /ustht sortin → Agent 处理 raw/ → 按维度追加到 mdbase/
         ↓
用户执行 /ustht mdbase show → Agent 展示组织好的想法库

工作模式

• 被动模式（INSTANT_STATUS=off）：仅响应技能命令，不自动识别想法
• 即时计划模式（INSTANT_STATUS=on 且 SKILL_STATUS=on）：自动识别用户想法并写入 #raw/，mdbase 写入延迟到 sortin
• 忽略模式：ignore start/end 区间内发言不记入
• 只读模式（必需工具缺失时）：只读命令可用，写入命令返回提示

模式组合：即时计划 + 忽略可同时生效。SKILL_STATUS=off 时即时计划自动暂停，无论 INSTANT_STATUS 值如何。被动/即时计划通过 define.ini 持久化；忽略区间仅上下文有效。

---

目录定义

• @/：SKILL 安装目录（SKILL.md 所在目录，即 user-thoughts/）
• ~/：工作目录
• #ustht/ = ~/.ustht/（.ustht 是 user-thoughts 的运行时缩写）
• #mdbase/ = ~/.ustht/mdbase/
• #ignored/ = ~/.ustht/ignored/
• #raw/ = ~/.ustht/raw/
• #export/ = ~/.ustht/export/

---

#ustht 目录结构

.ustht/
├── define.ini           # SKILL 运行状态
├── README.ai.md         # .ustht/ 目录说明
├── raw/                 # 用户原始发言(按日期分片)
│   └── yyyy-mm-dd.md
├── ignored/             # 被标记忽略的发言
│   └── yyyy-mm-dd.md
├── mdbase/              # 整理后的用户想法库
│   ├── backlog.md       # 待办事项（用户明确提出但尚未开始的事项，由 sortin 归入）
│   ├── README.ai.md     # mdbase 索引与概览
│   └── details/         # 按维度组织的想法文件
│       ├── rules.md     # 项目规则、约束、原则
│       ├── plans.md     # 项目规划、方向性想法
│       ├── ui/
│       │   ├── outline.md  # UI 整体设计
│       │   └── details.md  # UI 细节设计
│       ├── dev-stack.md # 技术栈选型、框架决策
│       ├── general.md   # 通用（不属于其他维度的想法）
│       └── ...          # 按需扩展
└── export/              # 从 mdbase 导出的内容

---

工具与环境

依赖（本 SKILL 不提供）：

• read/write（必需）：读写 #ustht/ 下各文件，也用于初始化时逐文件复制模板
• bash（必需）：目录创建、文件删除。不使用 cp -r 等递归命令（防止符号链接攻击）
• SubAgent（可选）：并行维护 mdbase 维度文件

SubAgent 可用时必须使用，不得由主 Agent 自行维护。原因：mdbase 维护涉及多文件读写，SubAgent 可并行处理各维度文件，显著减少主 Agent 的上下文占用和执行时间。SubAgent 不可用时主 Agent 才直接执行。

必需工具缺失时向用户发出警告，SKILL 进入只读模式：只读命令（mdbase show、raw、status、ignore show）仍可用，写入命令（sortin、write_raw、ignore start/end、ignore --last、init）返回提示。

内置脚本

@/scripts/ 下提供 Python 脚本，Agent 可通过 bash 直接调用，减少多文件操作的 token 消耗：

脚本	用途	调用示例
common.py	共享工具函数（供其他脚本导入）	不直接调用
status.py	显示当前状态	python @/scripts/status.py
init.py	初始化 .ustht/	python @/scripts/init.py
show_raw.py	查看未处理 raw	python @/scripts/show_raw.py
show_mdbase.py	查看 mdbase 索引/维度	python @/scripts/show_mdbase.py show [--all|--维度名]
sortin.py	执行软维护	python @/scripts/sortin.py [--dry]
write_raw.py	写入 raw 条目	python @/scripts/write_raw.py "想法" [--dim 维度]
toggle.py	切换状态	python @/scripts/toggle.py skill|instant [on|off]
ignore_ops.py	忽略操作	python @/scripts/ignore_ops.py show|remove_last|add_suffix

resort（硬维护） 无独立脚本——该操作需要 Agent 语义分析（去重、归类、合并），由 Agent 直接执行。

脚本自动检测工作目录下的 .ustht/，无需手动指定路径。所有脚本支持 --help 参数查看详细用法。优先使用脚本处理机械性操作，将 Agent 的上下文留给语义分析（如维度归类）。

---

语法定义

本文档中 &[keyname] 表示引用 #ustht/define.ini 中 keyname 的值，是文档内的简写记法。Agent 通过读取 define.ini 获取实际值。define.ini 的写入由 sortin/resort/init 通过整文件覆写完成，不使用 &[keyname]=value 语法。

键名	类型	说明
SKILL_STATUS	on|off	技能启用状态
INSTANT_STATUS	on|off	即时计划启用状态（需 SKILL_STATUS=on 才生效）
LAST_SORTIN	yyyy-mm-dd HH:MM	上次 sortin 时间戳

---

技能命令

命令以 /user-thoughts 或 /ustht 引导，两者等价。完整正则语法和自然语言映射见 references/commands.md。

状态与开关

• /ustht init — 初始化工作目录（创建 .ustht/ 及模板）
• /ustht status — 输出全部状态（SKILL_STATUS、INSTANT_STATUS、LAST_SORTIN、未处理 raw 文件数、mdbase 维度文件数）
• /ustht skill — 输出技能状态
• /ustht skill on|off — 开启/关闭技能
• /ustht instant — 输出即时计划状态
• /ustht instant on|off — 开启/关闭即时计划

维护流程

• /ustht sortin [--dry] — 软维护（追加新想法），--dry 预览不写入
• /ustht resort [--dry] — 硬维护（重整全部 mdbase），--dry 预览不写入

忽略管理

• /ustht ignore start|end — 开始/结束忽略区间（仅上下文有效）
• /ustht ignore --last — 忽略上一条已记录的想法（从 raw 中删除该条目，记入 #ignored/；若 raw 文件变空，保留空文件不删除）
• /ustht ignore — 独立使用时等价于 --last（优先匹配全行命令正则，不触发后缀模式）
• /ustht ignore show — 列举 #ignored/ 目录内容（只读命令，SKILL 关闭时仍可用）
• .*/ustht ignore — 后缀模式，忽略本条消息的想法（不记入 raw，记入 #ignored/；不受 SKILL_STATUS 控制）

内容查看与导出

• /ustht raw — 查看未处理的 raw 记录
• /ustht mdbase show [--all|--维度名] — 查看索引或指定维度
• /ustht mdbase export [--all|--维度名] — 导出到 #export/
• /ustht import <路径> — 扫描路径下 .md 文件，并入 mdbase

触发规则： 用户发言匹配命令，或自然语言意图明确指向唯一命令时触发。详细映射见 references/commands.md。

链式命令： 使用 && 连接多条命令，按顺序依次执行。如 /ustht skill on && instant on。

---

即时计划

当 &[INSTANT_STATUS] 为 on 时自动执行：

1. 识别：判断用户发言是否包含项目想法、决策、需求、规则、偏好
2. 制订计划：写入 #raw/ 当天日期.md，格式 - [HH:MM] 想法原文 | 待归入:预判维度
3. 不执行：不改动 mdbase，延迟到 sortin 时统一执行
4. 过滤：忽略区间内或末尾携带 /ustht ignore（或 /user-thoughts ignore）的发言不写入
5. 不中断：后台静默执行，不打断正常对话
6. 自动建议：单日 raw 条目超过 5 条时，主动建议用户执行 sortin

---

维护流程

流程入参：sortin 软维护（追加）| resort 硬维护（重整）。

1. 读取 #raw/ 全部 .md，过滤掉已含 <!-- processed --> 标记的文件
2. 逐条分析归属维度
3. 追加（soft）或重整（hard）mdbase 对应文件
4. 在已处理 raw 文件头部插入 <!-- processed --> 标记
5. 更新 define.ini 中 LAST_SORTIN 时间戳
6. 更新 #mdbase/README.ai.md 索引和概要
7. 输出摘要

维度文件管理、raw 状态机制详见 references/sortin.md。

---

第一次使用

当工作目录下不存在 .ustht/ 时，Agent 自动触发 /ustht init，或用户手动执行：

1. 在 ~/ 创建 .ustht/ 目录
2. 复制 @/assets/Runtime-Template/ 全部内容到 #ustht/
3. 用 bash 创建 #raw/、#ignored/、#export/ 目录（若模板未包含）
4. 确认 define.ini 包含完整键值（SKILL_STATUS、INSTANT_STATUS、LAST_SORTIN）
5. 输出初始化确认：目录结构概览 + 可用命令列表（命令以 /ustht 形式展示）

已存在 .ustht/ 时执行 /ustht init：输出提示"已初始化"，不覆盖。

---

示例

基本对话捕获

User: "登录页用 OAuth2，别用 JWT——上个项目吃过 token 过期的亏。"
Agent: [即时计划] 已记录到 raw/2026-05-31.md

User: "/ustht sortin"
Agent: [sortin] 1 条新想法归入 rules.md

User: "/ustht mdbase show rules"
Agent:
  ## rules.md
  - [2026-05-31 14:00] 登录页用 OAuth2，别用 JWT——上个项目吃过 token 过期的亏。

忽略区间

User: "/ustht ignore start"
User: "今天天气不错，中午吃什么？"
User: "/ustht ignore end"
User: "首页按钮改成圆角 8px"
Agent: [即时计划] 已记录到 raw/2026-05-31.md（仅"圆角 8px"一条）

跨会话接手

[会话 1]
User: "Next.js + Prisma，不要 MongoDB。暗色主题优先。"
Agent: [即时计划] 已记录

[会话 2 / 不同 Agent]
Agent 读取 .ustht/mdbase/ → 已知技术栈和 UI 偏好 → 直接实现

---

最佳实践

• ✅ 用户发言优先：明确表述都应记录，不得以 Agent 判断为由忽略——用户说了就记，这是用户的决策库，不是 Agent 的判断库
• ✅ 不过度推断：只记录用户明确表达或可直接推导的想法——过度推断会污染 mdbase，让用户难以分辨哪些是自己的原意
• ✅ 保持原文：保留用户原始表述，不简化、不改写、不丢失细节。sortin 的"格式化"仅指：去除 raw 中的时间戳前缀和 | 待归入:维度名 后缀，按日期分组加标题，不改动想法正文。原文中的否定句、具体数值、限定条件都是关键意图，丢失它们等于丢失决策
• ✅ 维度归类：优先归入已有维度，无合适维度则归入 general.md，待办类想法归入 backlog.md（注意：backlog.md 存储在 mdbase/ 根目录而非 details/ 下，与其他维度不同）
• ✅ 冲突处理：以最新发言为准，原记录标注被替代并附日期——用户的决策会演进，保留历史但以最新为准
• ✅ 单条多想法拆分：一条消息包含多个独立想法时，拆分为多条记录——便于 sortin 按维度分别归类
• ❌ 非项目内容不记录：闲聊、与项目无关的话题不记入想法——mdbase 是项目决策库，不是聊天日志

---

局限性

• 本 SKILL 不能替代用户自身的判断——Agent 按规则记录，但不验证想法的可行性或一致性，这是有意为之：mdbase 是用户的决策记录，不是 Agent 的建议系统
• sortin 的维度归类依赖 Agent 语义分析，可能需要用户通过 resort 纠正——语义理解有边界，用户纠正是正常的迭代过程
• 忽略区间仅在当前上下文有效，跨会话自动失效——忽略通常是临时性需求，持久化反而可能造成意外遗漏
• .ustht/ 目录的安全性由用户保障，SKILL 不做脱敏处理——保持原文原则要求不修改内容，敏感数据由用户通过 ignore 主动管理

---

安全规范

• 路径安全：维度名每段仅允许 [a-z0-9] 开头和结尾的 [a-z0-9-] 序列，支持 / 作为子目录分隔符（如 ui/outline），禁止 ..、\——维度名会被拼接为文件路径，特殊字符可能导致路径遍历攻击。所有操作限制在 #ustht/ 内
• 内容安全：想法原文保留不转义，<!-- processed --> 仅检查文件第一行——防止用户想法中的标记字符串干扰 sortin 判断
• define.ini 安全：值不得含换行符或 =——防止键值注入。写入使用整文件覆写
• bash 安全：不执行用户任意 shell 命令，文件名从已验证维度名构造——防止命令注入
• 敏感数据：不脱敏，用户通过 ignore 主动排除，.ustht/ 安全性由用户保障

完整安全规范见 references/safety.md。

---

常见陷阱

• ignore 区间不持久化：ignore start 仅在当前上下文有效，跨会话自动失效——这是设计选择，不是缺陷，因为忽略意图通常只对当前对话有意义
• 命令与想法共存时：先执行命令，再做想法记录，顺序不可颠倒。命令触发词本身不记入想法内容
• raw 的 <!-- processed --> 标记：必须在文件第一行，不能放在其他位置——sortin 仅检查第一行来判断文件是否已处理
• sortin 不锁文件：依赖 Agent 协调，sortin 期间新发言正常记入 raw
• 不主动删除维度文件：用户明确要求时才标记 <!-- deprecated -->，不物理删除——保留历史可追溯性
• resort 模式：不是只追加，而是去重、归类、合并，必要时调整结构——与 sortin 的"只追加"策略不同
• ignore --last 无上一条：返回提示，不报错——静默失败比报错更符合忽略操作的语义
• 维度名验证：每段须以 [a-z0-9] 开头和结尾，仅 [a-z0-9-]，支持 / 子目录分隔，含 ..、\ 的参数必须拒绝——防止路径遍历攻击
• define.ini 写入：值不得含换行符或 =，整文件覆写不追加——防止键值注入
• 通用兜底：无法归入已有维度的想法追加到 general.md，不轻易新建维度——维度膨胀会降低 mdbase 的可用性

---

边界场景

• SKILL 关闭后：文件保留，写入类命令（sortin、ignore start/end、ignore --last、init）返回提示，只读命令（mdbase show、raw、status、ignore show）仍可用。后缀模式 .../ustht ignore 不受 SKILL_STATUS 控制
• 跨会话恢复：读取 define.ini 恢复状态，忽略区间不恢复
• 多项目隔离：各工作目录独立 .ustht/，互不影响

更多边界场景和完整交互示例见 references/edge-cases.md。

---

关联技能

• 无直接关联技能。本 SKILL 专注于用户想法的持久化，与其他技能无依赖关系。