feat(cli): doc view + unlink (fill v0.3 design-gap audit)
Final design-pass audit on the v0.3 surface flagged two real gaps.
(A) doc view <id> was missing. Every other resource subtree exposes
a view verb (kb view, session view) for inspecting a single record,
but doc — which has the richest metadata of the three (title, file
name, type, size, parse_status, embedding_model, processed_at,
error_message) — had no single-doc surface. Users wanting one
doc's metadata had to `doc list | grep`.
Implementation mirrors kb view: narrow ViewService(GetKnowledge)
interface, --json envelope path, human KEY: VALUE renderer. Optional
fields are omitted rather than rendered as "-" so the panel is
dense. Tested: human renderer, title fallback when FileName empty,
omit-empty contract, JSON envelope shape, 404 classification.
(B) link had no counterpart. Once .weknora/project.yaml is written,
the only way to clear it was `rm` by hand. Both vercel and netlify
ship `unlink` as a top-level verb; not having one was a
discoverability gap. Top-level rather than `link --clear` follows
the verb-noun convention of the rest of the surface — the verb
stands alone and the operation isn't parameterised.
unlink walks up from cwd via projectlink.Discover (the same
parent-chain logic Factory.ResolveKB uses on the read side), so a
user in a subdirectory of a linked project can unlink without
cd-ing up. Errors with input.invalid_argument when no link is
found anywhere in the chain. Idempotent under racy concurrent
removal: os.ErrNotExist on os.Remove falls through to a Success
envelope since the post-condition holds either way.
projectlink package gained Remove() alongside Save / Load /
Discover so unlink doesn't reimplement the idempotent-remove
pattern inline.
Top-level registration in cmd/root.go, alongside link.
cli/AGENTS.md verb canon line adds unlink to the locally-introduced
list. cli/CHANGELOG.md gains an Added entry for each.
5 unit tests for view + 4 for unlink (cwd / walk-up / no-link
error / JSON envelope). Full suite green.
Intentionally deferred:
- session edit (rename a session): sessions auto-name from the
first prompt; polish rather than a gap.
- link --clear as an alternative to unlink: top-level unlink is
the documented form; aliases would just multiply the surface.
2026-05-13 08:40:43 +00:00
|
|
|
// Package doc implements the `weknora doc` subtree (list / view / upload /
|
2026-05-21 10:42:27 +00:00
|
|
|
// fetch / create / download / delete / wait). Upload supports --recursive /
|
|
|
|
|
// --glob for bulk ingestion from local files. Fetch ingests a remote URL.
|
|
|
|
|
// Create adds a knowledge entry from inline text content.
|
2026-05-10 18:44:06 +00:00
|
|
|
//
|
|
|
|
|
// "Doc" is the CLI noun; the underlying SDK type is `Knowledge`. The renaming
|
|
|
|
|
// is deliberate: end-users think of a knowledge entry as the document they
|
|
|
|
|
// uploaded, not as an abstract knowledge unit. Mapping happens in this package
|
refactor(cli): drop aiclient package; align AGENTS.md with mainstream
Survey of 10 mainstream CLIs (gh, lark, stripe, vercel, supabase, aws,
azure, gcloud, openai/codex, github-copilot-cli) showed env-gated
per-command --help blurbs are a Stripe-only pattern; gh uses env detect
for telemetry only, and lark relies on installed agent Skills + MCP.
Our cmd/mcp/serve already covers the dominant 2025/26 path, so
internal/aiclient/ (136 LOC + 38 callsites) is net maintenance burden
without precedent.
- Drop internal/aiclient/ entirely (annotations + detect + tests)
- Remove 38 SetAgentHelp callsites + agentAwareHelpFunc / SetHelpFunc
wiring in cmd/root.go
- Migrate 4 command-level rules to standard Long help (visible to all,
not env-gated): doc upload mode mutex, kb edit at-least-one,
kb pin idempotent, search chunks channel mutex
- Rewrite AGENTS.md as a developer guide (gh-style 6 H2 / 167 lines):
audience preamble + Build / Architecture / Command Structure /
Testing / Code Style / Error Handling. Drops sections absent in
surveyed projects (Commit & PR Conventions, Who Uses This CLI)
- Clean 14 internal doc refs (ADR-N, spec §X, v0.X) in source comments
and docs that pointed at docs/superpowers/ — that directory is
local-only / uncommitted, so refs are dead for outside readers
- Drop forward-looking "once v0.2 ships" from README
2026-05-14 18:16:45 +00:00
|
|
|
// only - the SDK surface and server API keep the original spelling.
|
2026-05-10 18:44:06 +00:00
|
|
|
package doc
|
|
|
|
|
|
|
|
|
|
import (
|
|
|
|
|
"github.com/spf13/cobra"
|
|
|
|
|
|
|
|
|
|
"github.com/Tencent/WeKnora/cli/internal/cmdutil"
|
|
|
|
|
)
|
|
|
|
|
|
|
|
|
|
// NewCmd builds the `weknora doc` parent command.
|
|
|
|
|
func NewCmd(f *cmdutil.Factory) *cobra.Command {
|
|
|
|
|
cmd := &cobra.Command{
|
|
|
|
|
Use: "doc",
|
|
|
|
|
Short: "Manage documents in a knowledge base",
|
|
|
|
|
}
|
2026-05-21 10:42:27 +00:00
|
|
|
cmd.AddCommand(NewCmdCreate(f))
|
|
|
|
|
cmd.AddCommand(NewCmdDelete(f))
|
|
|
|
|
cmd.AddCommand(NewCmdDownload(f))
|
|
|
|
|
cmd.AddCommand(NewCmdFetch(f))
|
2026-05-10 18:44:06 +00:00
|
|
|
cmd.AddCommand(NewCmdList(f))
|
2026-06-26 12:40:59 +00:00
|
|
|
cmd.AddCommand(NewCmdReparse(f))
|
|
|
|
|
cmd.AddCommand(NewCmdUpdate(f))
|
2026-05-10 18:44:06 +00:00
|
|
|
cmd.AddCommand(NewCmdUpload(f))
|
2026-05-21 10:42:27 +00:00
|
|
|
cmd.AddCommand(NewCmdView(f))
|
2026-05-17 17:38:01 +00:00
|
|
|
cmd.AddCommand(NewCmdWait(f))
|
2026-05-10 18:44:06 +00:00
|
|
|
return cmd
|
|
|
|
|
}
|