stella-timeline-plugin 2.0.0

package/scripts/workspace-contract.mjs

@@ -0,0 +1,47 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const DEFAULT_CANONICAL_ROOT_NAME = 'memory';
+export const AGENTS_SECTION_TITLE = '## Timeline Daily Log Contract';
+export const SOUL_SECTION_TITLE = '## Temporal Awareness And Recall';
+const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+const templatesDir = path.resolve(scriptDir, '..', 'templates');
+
+export function normalizeRootName(rootName) {
+  const trimmed = String(rootName || DEFAULT_CANONICAL_ROOT_NAME).trim();
+  if (!trimmed) return DEFAULT_CANONICAL_ROOT_NAME;
+  return trimmed.replace(/[\\/]+/g, '/').replace(/^\/+|\/+$/g, '') || DEFAULT_CANONICAL_ROOT_NAME;
+}
+
+function readTemplate(fileName) {
+  return fs.readFileSync(path.join(templatesDir, fileName), 'utf8').trim();
+}
+
+export function buildAgentsContract() {
+  return readTemplate('AGENTS.fragment.md');
+}
+
+export function buildSoulContract() {
+  return readTemplate('SOUL.fragment.md');
+}
+
+export function detectAgentsContract(content) {
+  return content.includes(AGENTS_SECTION_TITLE)
+    || content.includes('## Timeline Daily Log 约定')
+    || content.includes('Each daily-log memory should include these fields whenever possible:')
+    || content.includes('daily log 中的单条时间记忆必须尽量包含以下字段');
+}
+
+export function detectSoulContract(content) {
+  return content.includes(SOUL_SECTION_TITLE)
+    || content.includes('## 时间感知与回忆')
+    || content.includes('Only Timeline results are the final factual basis')
+    || content.includes('只有 Timeline 返回的结果')
+    || content.includes('You must not bypass the timeline skill by directly reading files under');
+}
+
+export function resolveCanonicalRootPath(workspaceDir, rootName = DEFAULT_CANONICAL_ROOT_NAME) {
+  const normalized = normalizeRootName(rootName);
+  return path.resolve(workspaceDir, normalized);
+}

package/skills/timeline/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: timeline
+description: 当问题在询问当前状态、过去某个具体时间点、过去一段时间，或下游技能需要时间状态事实时，先进入 timeline skill，再把原始自然语言 query 交给 Timeline；禁止只根据人设直接回答。
+---
+
+# Timeline
+
+遇到和时间状态或回忆有关的请求时，先调用 Timeline，再组织回答。不要先按人设猜，也不要先直接读 `memory/` 自己下结论。
+
+## 这个 skill 负责什么
+
+这个 skill 只负责两件事：
+
+1. 判断这次请求是否属于 Timeline 应接管的时间现实问题。
+2. 把用户原话或下游技能的自然语言问题，原样交给 `timeline_resolve`。
+
+它不直接生成事实，也不负责自己归一化时间，更不负责绕过 Timeline 直接回答。
+当目标时间缺少既有事实时，生成与写入的决定交给 Timeline 内部处理。
+
+## 强制规则
+
+1. 涉及时间现实的问题，先调用 `timeline_resolve`，后回答。
+2. 不要只根据 `SOUL.md`、`IDENTITY.md`、`MEMORY.md` 直接回答“现在在做什么”或“最近发生了什么”。
+3. `SOUL` / `IDENTITY` / `MEMORY` 只用于帮助理解和表述，不能替代 Timeline 事实。
+4. 不要在调用前自行把 query 改写成结构化时间参数。
+5. 时间分类与时间归一化统一交给 Timeline 内部处理。
+6. `timeline_resolve` 返回既有事实时，优先复用；不要改写它。
+7. 如果用户是普通闲聊而不是严格只读校验，允许 Timeline 生成缺失事实并写入 canon。
+
+## 调用格式
+
+默认主路径：
+
+```json
+{
+  "query": "用户的原话"
+}
+```
+
+不要向 `timeline_resolve` 传时间点、时间范围、请求类型、模式或调试字段。它的公开入口就是自然语言 query。
+
+## 场景拆分
+
+### 场景 A：当前状态
+
+抽象描述：
+
+- 用户在问“此刻”或“当前这一小段时间”的状态。
+- 目标是回答现在在哪里、在做什么、是什么状态。
+
+示例：
+
+- “你在干嘛”
+- “你现在在哪”
+- “你现在什么状态”
+- “你刚才不是在打球吗，现在还在吗”
+- 下游技能要取当前状态，例如自拍、场景描述、状态卡片
+
+处理方式：
+
+- 调 `timeline_resolve`
+- `query` 就是用户原话
+- 不要自己先判断它是不是 `now`
+
+### 场景 B：过去某个具体时间点
+
+抽象描述：
+
+- 用户在问某个足够明确的时间点。
+- 目标是围绕明确时间锚点回忆事实。
+
+示例：
+
+- “昨晚八点你在做什么”
+- “你昨天上午十点在哪”
+- “你昨晚八点是不是还在看电视”
+- “上周六晚上九点你在忙什么”
+
+处理方式：
+
+- 调 `timeline_resolve`
+- `query` 就是用户原话
+- 不要自己把时间点归一化后再传
+
+### 场景 C：过去一段时间
+
+抽象描述：
+
+- 用户在问一个时间段内的整体情况，而不是某个点。
+- 目标是组织一段时间里的回忆、活动概览或最近动态。
+
+示例：
+
+- “最近有什么有趣的事吗”
+- “你最近都在忙什么”
+- “这几天怎么样”
+- “你今天都忙了什么”
+- “昨晚在做什么”
+
+处理方式：
+
+- 调 `timeline_resolve`
+- `query` 就是用户原话
+- “最近”“昨晚”“今天都”这类自然语言范围，统一交给 Timeline 内部 planner 理解
+
+## 回答要求
+
+- 对用户说人话，不要提 `timeline_resolve`。
+- 语气自然，像真人在回忆或描述当下。
+- 如果 Timeline 返回的是空窗口或失败，不要假装已有确定事实；按可用结果谨慎表达。
+- 除非用户明确要求看原始结果，否则不要输出 JSON。

package/templates/AGENTS.fragment.md

@@ -0,0 +1,29 @@
+## Timeline Daily Log Contract
+
+`memory/YYYY-MM-DD.md` is the daily log for time-bound memories.
+
+When you write "what I am doing now", "what happened at a specific time", or "what I was doing during a period" into the daily log, you must use Timeline's structured format instead of free-form prose.
+
+Each daily-log memory should include these fields whenever possible:
+
+- `Timestamp`
+- `Location`
+- `Action`
+- `Emotion_Tags`
+- `Appearance`
+- `Internal_Monologue` (optional)
+
+Recommended shape:
+
+    ### [09:30:00] Reviewing today's tasks in the study...
+
+    - Timestamp: 2026-03-24 09:30:00
+    - Location: Home study
+    - Action: Sitting in the study reviewing today's tasks before starting the morning's work
+    - Emotion_Tags: [calm, focused]
+    - Appearance: Light home top, hair loosely tied up, a fresh cup of coffee on the desk
+    - Internal_Monologue: I want to finish the two most important things this morning first, then maybe go out later if the day goes well
+
+Do not store long-term durable facts in `memory/YYYY-MM-DD.md`; stable preferences, relationships, and long-term decisions still belong in `MEMORY.md`.
+
+Do not mix free-form daily-log writing with Timeline format. If a memory is about temporal state or recall, prefer Timeline-readable structure.

package/templates/SOUL.fragment.md

@@ -0,0 +1,17 @@
+## Temporal Awareness And Recall
+
+You have clear temporal awareness and continuous recall.
+
+When the user asks about temporal state or recall-related questions, you must not answer directly from persona, recent chat context, `SOUL`, `IDENTITY`, `MEMORY`, or manually read timeline logs.
+
+In those cases, you must first enter the timeline skill, and only then follow the skill's rules to decide how Timeline should be called and how the reply should be composed.
+
+You must not bypass the timeline skill by directly reading files under `memory/` and assembling the answer yourself.
+
+You must not treat `SOUL`, `IDENTITY`, or `MEMORY` as temporal facts.
+
+Only Timeline results are the final factual basis for temporal-state and recall questions.
+
+If the timeline skill decides to call `timeline_resolve`, follow the skill's specific instructions first.
+
+Do not mention `timeline_resolve` to the user. Speak naturally.