Skip to content

README.vi.md

Latest commit

 

History

History
559 lines (405 loc) · 18.5 KB

README.vi.md

File metadata and controls

559 lines (405 loc) · 18.5 KB

Knowns

Knowns

Go npm CI Platform License

Trang chủ | English | Tài liệu

Cho AI coding assistant truy cập có cấu trúc vào task, doc, spec, và decision — để nó khỏi đoán mò.

Mỗi lần mở session mới với AI, bạn lại phải giải thích lại architecture, paste doc, nhắc lại convention, làm rõ decision cũ. AI rất mạnh — nhưng nó không nhớ gì giữa các session.

Knowns fix đúng chỗ đó. Cho AI assistants như Claude, Cursor, Copilot truy cập bền vững vào task, doc, spec, acceptance criteria, và architectural decisions của project. Thay vì prompt từ đầu, AI đọc đúng phần nó cần và tiếp tục từ chỗ bạn dừng.

Nếu bạn nghĩ AI nên thực sự hiểu software project, cho Knowns một star nhé.

Knowns task workflow demo

Mục lục

Tại sao cần Knowns?

AI coding assistants là stateless. Mỗi session bắt đầu từ zero.

Kết quả là bạn phải làm đi làm lại:

  • Giải thích lại architecture và design patterns
  • Paste lại doc vào chat
  • Nhắc lại coding conventions
  • Làm rõ lại decision đã chốt tuần trước
  • Dựng lại context mất 20 phút chuẩn bị

AI không thiếu thông minh. Nó thiếu quyền truy cập vào những gì project đã biết.

Knowns cho nó quyền truy cập đó.

Trước và sau

Không có Knowns Có Knowns
"Bọn tôi dùng repository pattern..." (paste 50 dòng) AI tự đọc @doc/patterns/repository
"Đây là task, AC là..." (gõ lại từ đầu) AI đọc task, AC, linked spec và related docs
"Nhớ tuần trước quyết định..." (hy vọng nó nhớ) Decision lưu trong project memory — AI recall mỗi session
"Auth flow hoạt động thế này..." (giải thích lần thứ 4) AI follow @doc/architecture/auth và build tiếp
"Xong chưa nhỉ, để check lại requirements..." AI tự check AC và validate completion
Session bắt đầu lạnh — mất 10 phút dựng context Session bắt đầu ấm — AI đã biết project

Knowns là gì?

Knowns là local-first, self-hostable project context layer cho AI-native development.

Lưu project knowledge dưới dạng structured, AI-readable files — và expose cho AI assistants qua CLI và MCP (Model Context Protocol).

Knowns Knowledge Graph

Cụ thể, Knowns quản lý:

  • Tasks với acceptance criteria, implementation plans, status tracking
  • Documentation trong nested markdown folders có cross-references
  • Specs define "xong" nghĩa là gì cho một feature
  • Memory — project-level, session-level, global knowledge để AI recall
  • Templates cho code generation bằng Handlebars
  • References như @task-42 và @doc/patterns/auth để AI follow và resolve
  • Code intelligence — AST-indexed symbols, dependency graphs, semantic code search

Tất cả nằm trong .knowns/ của repo. Plain files. Commit vào Git được. Không cần cloud.

Dành cho ai?

  • Solo developers pair với AI hằng ngày, muốn AI nhớ project context across sessions
  • Teams dùng AI assistants, chán cảnh ai cũng phải giải thích lại architecture
  • Open-source maintainers muốn contributors (người hoặc AI) onboard nhanh hơn
  • Bất kỳ ai dùng Claude, Cursor, Copilot, Windsurf hay AI coding tools khác và muốn chúng thực sự hiểu project

Cách hoạt động

Knowns nằm cạnh tools bạn đang dùng. Stack hiện tại không cần đổi.

Knowns Architecture

  1. Bạn cấu trúc project knowledge — task, doc, spec, decision — bằng CLI hoặc Web UI
  2. AI đọc — qua MCP hoặc CLI, AI truy cập đúng context nó cần
  3. AI hành động — follow reference, check AC, update task status, build với full awareness
  4. Knowledge tích lũy — decision, pattern, convention persist across sessions

Spec → understood. Task → connected. Doc → usable. Decision → remembered.

Quick start

# Cài đặt
brew install knowns-dev/tap/knowns
# hoặc: npm install -g knowns
# hoặc: curl -fsSL https://knowns.sh/script/install | sh
# hoặc Windows PowerShell:
# irm https://knowns.sh/script/install.ps1 | iex

# Kiểm tra
knowns --version

# Init trong project
cd your-project
knowns init

# Hoặc chạy không cần cài global
npx knowns init

# Tạo task đầu tiên
knowns task create "Add user authentication" \
  -d "JWT-based auth with login and register endpoints" \
  --ac "User can register with email/password" \
  --ac "User can login and receive JWT token" \
  --ac "Protected routes reject unauthenticated requests"

# Thêm doc
knowns doc create "Auth Architecture" \
  -f "architecture" \
  -d "Authentication design decisions and patterns"

# Mở Web UI
knowns browser --open

# Update Knowns sau này
knowns update

# Kết nối AI assistant qua MCP
# Xem: docs/vi/guides/mcp-integration.md

Giờ khi AI đọc project, nó thấy structured tasks có AC, linked documentation, và clear definition of done — thay vì đoán.

Khả năng chính

Task & workflow management

Tạo task có acceptance criteria, implementation plan, status tracking. AI đọc task, follow plan, check AC, biết rõ khi nào xong.

knowns task create "Title" --ac "Criterion 1" --ac "Criterion 2"
knowns task edit <id> -s in-progress
knowns task edit <id> --check-ac 1

Structured documentation

Tổ chức project knowledge trong nested markdown folders. Cross-reference bằng @doc/path và @task-id. AI follow references để load đúng context cần dùng.

knowns doc create "API Design" -f "architecture"
knowns doc "architecture/api-design" --smart --plain

Project memory

Memory 3 layer — project, session, global — AI recall decisions, patterns, conventions mà không cần bạn nhắc lại.

knowns memory add "We use repository pattern for data access" --category decision
knowns memory list --plain

Semantic search

Tìm theo ý nghĩa, không chỉ keyword. Chạy local bằng ONNX models — offline hoàn toàn, không cần API key.

knowns search "how does authentication work" --plain

MCP integration

Full Model Context Protocol server. Claude, Cursor và các MCP-compatible assistants truy cập trực tiếp task, doc, memory, search, validation — không cần copy-paste.

Code intelligence

AST-based indexing cho Go, TypeScript, JavaScript, Python. Search symbols, trace dependencies, explore codebase structure — tất cả accessible cho AI.

knowns code ingest
knowns code search "oauth login" --neighbors 5
knowns code deps --type calls

Templates & code generation

Handlebars-based templates cho scaffolding. Define pattern một lần, generate nhất quán.

knowns template list
knowns template run <name> --name "UserService"

AI agent workspaces

Multi-phase agent orchestration với git worktree isolation, live terminal streaming, automatic phase progression (research → plan → implement → review).

Web UI

Kanban board, document browser, knowledge graph visualization, mermaid support — tất cả trong local browser UI.

knowns browser --open

Xây được gì với Knowns?

Khả năng Mô tả
Task Management Task có AC, plan, status, time tracking
Documentation Nested markdown folders có cross-references và mermaid
Semantic Search Tìm theo ý nghĩa với local AI models (offline)
Time Tracking Timer và report theo task
Context Linking @task-42 và @doc/patterns/auth references AI resolve được
Validation Phát hiện broken references và incomplete tasks bằng knowns validate
Template System Code generation bằng Handlebars (.hbs) templates
Import System Import docs và templates từ git, npm, local
Memory System Project / session / global memory cho persistent AI recall
MCP Server AI assistant integration với full tool access
AI Workspaces Multi-phase agent orchestration với worktree isolation
Code Intelligence AST indexing, symbol search, dependency graphs
Web UI Kanban board, doc browser, knowledge graph, mermaid diagrams

Claude Code skills workflow

Khi dùng Claude Code với Knowns, skills (slash commands) tạo guided workflow:

Knowns AI Workflow 

/kn-init      -> Đọc project docs, hiểu context
/kn-plan      -> Nhận task, gom context, tạo plan (chờ approve)
/kn-implement -> Follow plan, check AC, track progress
/kn-commit    -> Commit theo conventional format

Ví dụ session

Bạn: /kn-init
Claude: [Đọc README, ARCHITECTURE, check task backlog]
        "Project dùng NestJS với CQRS pattern. 3 tasks đang in-progress..."

Bạn: /kn-plan 42
Claude: [Nhận task, đọc refs, search docs]
        "Task #42: Add user authentication

         ## Implementation Plan
         1. Review @doc/patterns/auth
         2. Tạo AuthModule với JWT strategy
         3. Thêm login/register endpoints
         4. Viết unit tests

         Approve plan này?"

Bạn: OK

Bạn: /kn-implement 42
Claude: [Follow plan, generate code, check AC]
        "✓ AC1: User can login - DONE
         ✓ AC2: JWT token returned - DONE
         ✓ AC3: Tests pass - DONE

         Tất cả AC đã complete. Ready to commit?"

Bạn: /kn-commit
Claude: [Tạo conventional commit]
        "feat(auth): add JWT authentication

         - Add AuthModule with passport JWT strategy
         - Add login/register endpoints
         - Add unit tests (94% coverage)"

Skills

Skill Mô tả
/kn-init Init session — đọc docs, load memory, hiểu project
/kn-plan <id> Nhận task, gom context, tạo implementation plan
/kn-implement <id> Execute plan, track progress, check AC
/kn-research Search codebase, tìm patterns, explore trước khi code
/kn-commit Tạo conventional commit có verification
/kn-spec Tạo spec document cho feature (SDD)
/kn-go <spec> Full pipeline từ approved spec (không có review gates)
/kn-verify Chạy SDD verification và coverage report
/kn-review Multi-perspective code review (P1/P2/P3)
/kn-doc Tạo hoặc update doc
/kn-extract Extract reusable patterns vào docs, templates, memory
/kn-template List, run, hoặc tạo template
/kn-debug Debug errors với memory-backed triage

Cài đặt

Homebrew (macOS/Linux)

brew install knowns-dev/tap/knowns

Shell installer (macOS/Linux)

curl -fsSL https://knowns.sh/script/install | sh

# Hoặc wget
wget -qO- https://knowns.sh/script/install | sh

# Version cụ thể
curl -fsSL https://knowns.sh/script/install | KNOWNS_VERSION=0.18.0 sh

PowerShell installer (Windows)

irm https://knowns.sh/script/install.ps1 | iex

# Version cụ thể
$env:KNOWNS_VERSION = "0.18.0"; irm https://knowns.sh/script/install.ps1 | iex

Shell installer (macOS/Linux) và PowerShell installer (Windows) tự chạy knowns search --install-runtime sau khi cài binary. Nếu bước đó fail, chạy lại bằng tay.

npm

# Global install — tự tải binary theo platform
npm install -g knowns

# Hoặc chạy không cần cài
npx knowns

Build từ source (Go 1.24.2+)

go install github.com/howznguyen/knowns/cmd/knowns@latest

# Hoặc clone rồi build
git clone https://github.com/knowns-dev/knowns.git
cd knowns
make build        # Output: bin/knowns
make install      # Cài vào GOPATH/bin

Gỡ cài đặt

# macOS/Linux
curl -fsSL https://knowns.sh/script/uninstall | sh

# Windows
irm https://knowns.sh/script/uninstall.ps1 | iex

Uninstall scripts chỉ xóa CLI binary và PATH entries do installer thêm. Không đụng tới .knowns/ trong các project.

Tra cứu nhanh

# Tasks
knowns task create "Title" -d "Description" --ac "Criterion"
knowns task list --plain
knowns task <id> --plain
knowns task edit <id> -s in-progress -a @me
knowns task edit <id> --check-ac 1

# Documentation
knowns doc create "Title" -d "Description" -f "folder"
knowns doc "doc-name" --plain
knowns doc "doc-name" --smart --plain
knowns doc "doc-name" --section "2" --plain

# Templates
knowns template list
knowns template run <name> --name "X"
knowns template create <name>

# Imports
knowns import add <name> <source>
knowns import sync
knowns import list

# Time, Search & Validate
knowns time start <id> && knowns time stop
knowns search "query" --plain
knowns validate

# Code intelligence
knowns code ingest
knowns code search "oauth login" --neighbors 5
knowns code deps --type calls
knowns code symbols --kind function

# AI Guidelines
knowns agents --sync
knowns sync

Tài liệu

Guide Mô tả
Hướng dẫn sử dụng Bắt đầu và sử dụng hằng ngày
Lệnh CLI commands chính và ví dụ
Workflow Cách làm việc đề xuất
MCP MCP setup cho Claude, Cursor, Codex, OpenCode, ...
Reference system Cách @doc/ và @task- hoạt động
Semantic search Setup và sử dụng semantic search
Templates Code generation bằng Handlebars templates
Web UI Board, doc browser, graph, chat UI
Cấu hình Project config và options
Skills Skills và sync paths theo platform
Developer guide Cho người đóng góp
Platforms Platform integration mapping

Roadmap

AI Agent Workspaces ✅ (Active)

Multi-phase agent orchestration — giao task cho AI agents với git worktree isolation, live terminal streaming, automatic phase progression (research → plan → implement → review).

Self-Hosted Team Sync 🚧 (Planned)

Optional self-hosted sync server cho shared visibility mà không bỏ local-first.

  • Real-time visibility — biết ai đang làm gì
  • Shared knowledge — sync task và doc across team
  • Full data control — self-hosted, không phụ thuộc cloud

Development

Cần Go 1.24.2+ và tùy chọn Node.js + pnpm cho UI development.

make build              # Build binary -> bin/knowns
make dev                # Build với race detector
make test               # Unit tests
make test-e2e           # CLI + MCP E2E tests
make test-e2e-semantic  # E2E tests bao gồm semantic search
make lint               # golangci-lint
make cross-compile      # Build cho 6 platforms
make ui                 # Rebuild embedded Web UI (cần pnpm)

Project structure

cmd/knowns/          # CLI entry point
internal/
  cli/               # Cobra commands
  models/            # Domain models
  storage/           # File-based storage (.knowns/)
  server/            # HTTP server, SSE, WebSocket
    routes/          # REST API handlers
    workspace/       # Agent orchestrator, process manager, worktree
  mcp/               # MCP server (stdio)
  search/            # Semantic search (ONNX)
ui/                  # Embedded React UI (built assets)
tests/               # E2E tests

Links

Design principles và long-term direction: Philosophy.

Technical details: Architecture và Contributing.

Star History

Star History Chart

What your AI should have knowns.
Cho dev teams pair với AI.