mirror of
https://github.com/runkids/skillshare.git
synced 2026-11-20 12:23:22 +00:00
* feat(memory): add host-owned review and verification workflows Share scoped memory tools between Dashboard and Memory, and route retrospective and Dreaming requests through the built-in skill. Keep agent execution in the host, require approval for reviewed edits, and preserve versioned CLI write safeguards. Confirm scope before exposing prompts and include the resolved root in recent memory responses. Update provenance guidance and localized documentation, with regressions for unavailable scope and protected review prompts. * fix(memory): distinguish trial copy controls for screen readers Include the localized step title in each trial copy control accessible name while keeping the short visible label. Update the existing clipboard test selector for the distinct names; no new test or local test rerun was requested for this label-only fix. * fix(memory): point connection hints to the trial tools Replace stale verification-prompt directions in all eleven locales with the current Memory tools and Try across sessions labels. Interpolate the existing localized labels so future naming changes remain aligned. No new tests or local test reruns for this copy-only correction, as requested by the maintainer.
269 lines
11 KiB
Go
269 lines
11 KiB
Go
package memory
|
|
|
|
import (
|
|
"crypto/sha256"
|
|
"encoding/hex"
|
|
"fmt"
|
|
"path/filepath"
|
|
"regexp"
|
|
"strings"
|
|
)
|
|
|
|
// Guidance scopes. A global block and a project block can both reach one
|
|
// agent, so each names its scope and only its own scope is managed.
|
|
const (
|
|
ScopeGlobal = "global"
|
|
ScopeProject = "project"
|
|
)
|
|
|
|
// Block states, as reported for one file or target.
|
|
const (
|
|
StateUnconfigured = "unconfigured"
|
|
StateConfigured = "configured"
|
|
StateOutdated = "outdated"
|
|
StateModified = "modified" // the body no longer matches its recorded hash
|
|
StateMalformed = "malformed" // markers are unclosed, stray, or repeated
|
|
)
|
|
|
|
// Update modes. A passive agent only reads the notes; an active one also
|
|
// saves what will matter later. Each block records its own mode, so agents
|
|
// reading different files can differ.
|
|
const (
|
|
ModePassive = "passive"
|
|
ModeActive = "active"
|
|
)
|
|
|
|
const blockEnd = "<!-- /skillshare:memory -->"
|
|
|
|
// A passive block has no mode attribute, so blocks written before modes
|
|
// existed stay current.
|
|
var blockBegin = regexp.MustCompile(`^<!-- skillshare:memory scope=(global|project)(?: mode=(passive|active))? sha256=([0-9a-f]{16}) -->$`)
|
|
|
|
// ParseMode returns the mode named by s; empty means passive.
|
|
func ParseMode(s string) (string, error) {
|
|
switch s {
|
|
case "", ModePassive:
|
|
return ModePassive, nil
|
|
case ModeActive:
|
|
return ModeActive, nil
|
|
}
|
|
return "", fmt.Errorf("memory update mode must be %s or %s", ModePassive, ModeActive)
|
|
}
|
|
|
|
// Each rule names example facts with %s; the examples depend on the scope so a
|
|
// project decision has one destination when an agent reads both blocks.
|
|
const (
|
|
passiveRule = "Update these notes only when the user requests it. When you notice something worth keeping, such as %s, say so in one line so the user can ask you to save it."
|
|
activeRule = "A fact that will still matter in later sessions belongs here, not in this tool's own memory: %s. Use tool-specific memory only for things that matter to this tool alone. Skip one-off task details, guesses, and anything the repository already records. When you are unsure whether something is worth keeping, propose the note to the user and save it only if they agree.\n\nA fact that fits in one or two sentences goes directly under `## Notes` in `INDEX.md` as one bullet. Only a note that needs several paragraphs gets its own kebab-case `.md` file: first line `# Title`, then the fact and why, plus a `- [Title](file.md)` line with a short hook in `INDEX.md`. A lesson from a failure goes under a new heading in `LEARNED.md` with its date, context, conclusion, and evidence. Before writing, search the existing notes and update or remove them instead of adding a duplicate. Never record secrets."
|
|
recordRule = "When saving a decision or lesson, include the date, why it matters, and an available source or evidence (such as a user request, file, command result, or link). Distinguish confirmed facts from assumptions; do not invent dates or sources. Keep this in ordinary Markdown, without requiring a metadata schema. After a successful write, tell the user in one line what was saved or updated, whether it belongs to project or shared memory, and the saved file path. Never report a failed write as saved.\n\nWhen repeated corrections or conflicting notes reveal a useful review opportunity, suggest a session retrospective or Dreaming once in one short line. Use the Skillshare skill's memory-review reference when available, or ask for the scoped Memory tools prompt. Do not start the review without a request; propose concrete paths and edits for approval before changing reviewed notes."
|
|
globalExamples = "a stated user preference, a decision that applies across your projects with its reason, or a pitfall you confirmed in a tool you use"
|
|
projectExamples = "a decision about this project with its reason, a convention it follows, or a pitfall you confirmed in it"
|
|
)
|
|
|
|
// Instructions returns the managed guidance block of the given mode for the
|
|
// memory folder at root. projectRoot is empty in global mode; in project mode
|
|
// a folder inside the project is named relative to its root, so the text
|
|
// works in any checkout.
|
|
func Instructions(root, projectRoot, mode string) string {
|
|
scope, heading, dir := ScopeGlobal, "Shared memory", filepath.ToSlash(root)
|
|
where := "Shared notes directory: `" + dir + "`"
|
|
shared := "This folder is shared by every coding tool you use. A project with its own project memory keeps that project's notes there."
|
|
examples := globalExamples
|
|
if projectRoot != "" {
|
|
scope, heading = ScopeProject, "Project memory"
|
|
where = "Project notes directory: `" + dir + "`"
|
|
shared = "This folder is shared by every coding tool working in this project. Keep notes about this project here; notes about you, your tools, or other projects do not belong here."
|
|
examples = projectExamples
|
|
if rel, err := filepath.Rel(projectRoot, root); err == nil && rel != ".." && !strings.HasPrefix(rel, ".."+string(filepath.Separator)) && !filepath.IsAbs(rel) {
|
|
where = "Project notes directory: `" + filepath.ToSlash(rel) + "` (relative to the project root)"
|
|
}
|
|
}
|
|
rule := fmt.Sprintf(passiveRule, examples)
|
|
if mode == ModeActive {
|
|
rule = fmt.Sprintf(activeRule, examples)
|
|
} else {
|
|
mode = ModePassive
|
|
}
|
|
body := fmt.Sprintf("## %s\n\n%s\n\n%s Read `INDEX.md` at the start of each task; it is one short file. Open only the notes relevant to the task, and treat them as historical evidence: verify changeable claims before relying on them.\n\n%s\n\n%s", heading, where, shared, rule, recordRule)
|
|
return renderBlock(scope, mode, body, "\n")
|
|
}
|
|
|
|
func bodyHash(body string) string {
|
|
sum := sha256.Sum256([]byte(body))
|
|
return hex.EncodeToString(sum[:])[:16]
|
|
}
|
|
|
|
func renderBlock(scope, mode, body, eol string) string {
|
|
attr := ""
|
|
if mode == ModeActive {
|
|
attr = " mode=" + ModeActive
|
|
}
|
|
lines := []string{fmt.Sprintf("<!-- skillshare:memory scope=%s%s sha256=%s -->", scope, attr, bodyHash(body))}
|
|
lines = append(lines, strings.Split(body, "\n")...)
|
|
lines = append(lines, blockEnd)
|
|
return strings.Join(lines, eol) + eol
|
|
}
|
|
|
|
// span is one parsed block: its line range [start, end] and normalized body.
|
|
type span struct {
|
|
scope, mode string
|
|
start, end int
|
|
body, hash string
|
|
}
|
|
|
|
// parseBlocks finds managed blocks outside Markdown code: fenced blocks
|
|
// (``` or ~~~, closed by a run of the same character at least as long) and
|
|
// lines indented four or more spaces are examples, not markers. Any marker
|
|
// problem makes the whole file malformed, so nothing in it is rewritten.
|
|
func parseBlocks(lines []string) ([]span, bool) {
|
|
var out []span
|
|
var open *span
|
|
fenceChar, fenceLen := byte(0), 0
|
|
for i, raw := range lines {
|
|
raw = strings.TrimSuffix(raw, "\r")
|
|
indent := len(raw) - len(strings.TrimLeft(raw, " "))
|
|
line := strings.TrimSpace(raw)
|
|
if open == nil && indent < 4 && !strings.HasPrefix(raw, "\t") {
|
|
if c, n := fenceRun(line); n >= 3 {
|
|
switch {
|
|
case fenceLen == 0:
|
|
fenceChar, fenceLen = c, n
|
|
continue
|
|
case c == fenceChar && n >= fenceLen && strings.TrimLeft(line, string(c)) == "":
|
|
fenceChar, fenceLen = 0, 0
|
|
continue
|
|
}
|
|
}
|
|
}
|
|
if fenceLen > 0 || indent >= 4 || strings.HasPrefix(raw, "\t") {
|
|
continue
|
|
}
|
|
switch {
|
|
case line == blockEnd:
|
|
if open == nil {
|
|
return nil, false
|
|
}
|
|
open.end = i
|
|
body := make([]string, 0, i-open.start-1)
|
|
for _, l := range lines[open.start+1 : i] {
|
|
body = append(body, strings.TrimSuffix(l, "\r"))
|
|
}
|
|
open.body = strings.Join(body, "\n")
|
|
out = append(out, *open)
|
|
open = nil
|
|
case strings.HasPrefix(line, "<!-- skillshare:memory"):
|
|
m := blockBegin.FindStringSubmatch(line)
|
|
if m == nil || open != nil {
|
|
return nil, false
|
|
}
|
|
mode, _ := ParseMode(m[2])
|
|
open = &span{scope: m[1], mode: mode, start: i, hash: m[3]}
|
|
}
|
|
}
|
|
return out, open == nil
|
|
}
|
|
|
|
// fenceRun returns the fence character and run length a line starts with.
|
|
func fenceRun(line string) (byte, int) {
|
|
if line == "" || (line[0] != '`' && line[0] != '~') {
|
|
return 0, 0
|
|
}
|
|
n := len(line) - len(strings.TrimLeft(line, line[:1]))
|
|
if line[0] == '`' && strings.Contains(line[n:], "`") {
|
|
return 0, 0 // a backtick fence's info string cannot contain backticks
|
|
}
|
|
return line[0], n
|
|
}
|
|
|
|
// Inspect reports the state of the scope's block in content against want,
|
|
// the block Instructions returns now.
|
|
func Inspect(content, want string) string {
|
|
scope, wantMode, wantBody := splitWant(want)
|
|
blocks, ok := parseBlocks(strings.Split(content, "\n"))
|
|
if !ok {
|
|
return StateMalformed
|
|
}
|
|
var found *span
|
|
for i := range blocks {
|
|
if blocks[i].scope != scope {
|
|
continue
|
|
}
|
|
if found != nil {
|
|
return StateMalformed
|
|
}
|
|
found = &blocks[i]
|
|
}
|
|
switch {
|
|
case found == nil:
|
|
return StateUnconfigured
|
|
case bodyHash(found.body) != found.hash:
|
|
return StateModified
|
|
case found.body != wantBody || found.mode != wantMode:
|
|
return StateOutdated
|
|
}
|
|
return StateConfigured
|
|
}
|
|
|
|
// Apply returns content with the scope's block set to want: appended when
|
|
// absent, replaced when outdated. Other content is kept byte for byte. It
|
|
// refuses a modified or malformed block.
|
|
func Apply(content, want string) (string, error) {
|
|
switch state := Inspect(content, want); state {
|
|
case StateConfigured:
|
|
return content, nil
|
|
case StateUnconfigured:
|
|
if content == "" {
|
|
return want, nil
|
|
}
|
|
eol := "\n"
|
|
if strings.Contains(content, "\r\n") {
|
|
eol = "\r\n"
|
|
}
|
|
if !strings.HasSuffix(content, "\n") {
|
|
content += eol
|
|
}
|
|
scope, mode, body := splitWant(want)
|
|
return content + eol + renderBlock(scope, mode, body, eol), nil
|
|
case StateOutdated:
|
|
scope, mode, body := splitWant(want)
|
|
lines := strings.Split(content, "\n")
|
|
blocks, _ := parseBlocks(lines)
|
|
for _, b := range blocks {
|
|
if b.scope != scope {
|
|
continue
|
|
}
|
|
eol := "\n"
|
|
if strings.HasSuffix(lines[b.start], "\r") {
|
|
eol = "\r\n"
|
|
}
|
|
block := strings.Split(strings.TrimSuffix(renderBlock(scope, mode, body, eol), "\n"), "\n")
|
|
next := append(append(append([]string{}, lines[:b.start]...), block...), lines[b.end+1:]...)
|
|
return strings.Join(next, "\n"), nil
|
|
}
|
|
return "", fmt.Errorf("memory guidance block not found")
|
|
default:
|
|
return "", fmt.Errorf("memory guidance block is %s; edit it by hand or remove it first", state)
|
|
}
|
|
}
|
|
|
|
// Mode returns the mode of the scope's block in content, passive when there
|
|
// is none.
|
|
func Mode(content, scope string) string {
|
|
blocks, _ := parseBlocks(strings.Split(content, "\n"))
|
|
for _, b := range blocks {
|
|
if b.scope == scope {
|
|
return b.mode
|
|
}
|
|
}
|
|
return ModePassive
|
|
}
|
|
|
|
// splitWant returns the scope, mode and body of a block rendered by Instructions.
|
|
func splitWant(want string) (string, string, string) {
|
|
blocks, _ := parseBlocks(strings.Split(want, "\n"))
|
|
if len(blocks) != 1 {
|
|
return "", "", ""
|
|
}
|
|
return blocks[0].scope, blocks[0].mode, blocks[0].body
|
|
}
|